CMDI Best Practices Guide editing procedure

The best practices guide is edited in LaTeX on Overleaf.

Overleaf links for the draft document:

• ​Read
• ​Edit (ONLY to be used with editors, do NOT share publicly ! )

The document is organised into separate directories and files for the various sections and subsections. There is one MASTER document that defines the document structure and takes care of importing packages, defining some custom commands and other 'preamble' matter.

Editing - publication workflow

This document is regularly synchronised with the connected ​cmdi-best-practices GitHub repository.

Whenever a new version is to be published, new changes are merged into a ​main repository, from where version are built (via a ​private Overleaf project) and attached to ​releases.

Schematical overview:

 EDITS        SYNC              +->>>---MERGE->>>---+                   SYNC
   |           |                |                   |                    |
---+--------   |   -------------+---------      ----+-----------------   |   ------------
(1) Overleaf <---> (2) GitHub (draft fork)      (3) GitHub (main fork) <---> (4) Overleaf
------------       -----------------------      ----------------------       ------------
                                                         |                         |
                                                         |                         |
                                                         +--> (3a) Releases <--PDF-+

Links:

• (1) Overleaf (​read)
• (2) GitHub: ​cmdi-taskforce/cmdi-best-practices
• (3) GitHub: ​clarin-eric/cmdi-best-practices
  • (3a) ​clarin-eric/cmdi-best-practices/releases
• (4) Overleaf (​read)

See the CMDI Best Practices Guide publication procedure for a step-by-step description of the publication procedure.

Also see: CLARIN on GitHub

Draft mode

The guide can be compiled with draft mode either enabled or disabled. To toggle draft mode, change the following line in the MASTER file:

\setboolean{bpdraft}{true}

or

\setboolean{bpdraft}{false}

(default is false)

Work in progress

Sections that are work in progress can be marked as such which causes them to be visually marked as work in progress in draft mode, and omitted if the document is compiled in on-draft mode. To do so, wrap the content in a workinprogress block. For example:

\begin{workinprogress}
\section{My work in progress section}
...
This will appear (only if the document is compiled in draft mode) with a red line in the margin and markers at the beginning and end to indicate work in progress
...
\end{workinprogress}

Notes

The following commands are defined to make notes and inline TODO items (ommitted in compilation unless in draft mode) and various types of 'info boxes' anywhere in the document:

\bptodo{This message appears as an inline TODO note (only in draft mode)}

\note{This message appears as a note in the margin (only in draft mode)}

\priority{This is used to indicate priority level for a best practice}

\clarinb{This is used to indicate that a best practice matches a B-centre requirement}

\checker{This is used to indicate that a best practice can be automatically validated}

\pchecker{This is used to indicate that a best practice can partially be automatically validated}