= CMDI Best Practices Guide editing procedure =

The best practices guide is edited in LaTeX on Overleaf.

Overleaf links for the **draft document**:
  * [https://www.overleaf.com/read/wfsggvdjbbgj Read]
  * [https://www.overleaf.com/5272115735bdsxsshpmctp 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 [https://github.com/cmdi-taskforce/cmdi-best-practices cmdi-best-practices GitHub repository].

Whenever a new version is to be published, new changes are merged into a [https://github.com/clarin-eric/cmdi-best-practices main repository], from where version are built (via a [https://www.overleaf.com/read/jmfqrwhzmzss private Overleaf project]) and attached to [https://github.com/clarin-eric/cmdi-best-practices/releases '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 ([https://www.overleaf.com/read/wfsggvdjbbgj read])
* (2) !GitHub: [https://github.com/cmdi-taskforce/cmdi-best-practices cmdi-taskforce/cmdi-best-practices]
* (3) !GitHub: [https://github.com/clarin-eric/cmdi-best-practices clarin-eric/cmdi-best-practices]
  * (3a) [https://github.com/clarin-eric/cmdi-best-practices/releases clarin-eric/cmdi-best-practices/releases]
* (4) Overleaf ([https://www.overleaf.com/read/jmfqrwhzmzss read])

See the [[../BestPracticesPublishing|CMDI Best Practices Guide publication procedure]] for a step-by-step description of the publication procedure.

Also see: [[GitHub|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:

{{{
#!tex
\setboolean{bpdraft}{true}
}}}

or

{{{
#!tex
\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:

{{{
#!tex
\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:
{{{
#!tex
\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}
}}}