Open eCard

h1. Documentation Strategy

In order to allow distributed and convenient editing using the wiki 

*AND* producing documents with high quality typesetting, the following documentation 

strategy is implemented:

h2. Wiki is primary source

The primary editing is performed in the present Wiki, which uses the

Textile-markup as explained "here":http://www.redmine.org/projects/redmine/wiki/RedmineTextFormatting.

h2. Rules for Wiki-based documentation

In order to allow conversion to LaTeX, the following rules MUST be considered:

# A Wiki-page corresponds to a LaTeX-chapter and hence a Wiki-page SHOULD NOT include sub-Wiki-pages. 

# References to literature MAY be included, if they are included as link with brackets [ ] around the "LABEL" (e.g. "[BSI-TR-03112-7]":http://docs.ecsec.de/BSI-TR-03112-7),

where the LABEL SHOULD be defined in an appropriate BibTeX-file. 

h2. RedCloth conversion to raw LaTeX

The Textile-markup from the Wiki can be converted to LaTeX using "RedCloth":http://redcloth.org/.

h2. Cleaning up LaTeX using awk

In order to support references to documents (e.g. "[BSI-TR-03112-7]":http://docs.ecsec.de/BSI-TR-03112-7) or 

the inclusion of pretty-printed XML- or Java-code (e.g. <pre><code class="xml"><xml> ... </xml></code></pre>), the raw LaTeX document needs to be cleaned up with "awk":https://de.wikipedia.org/wiki/Awk.  

This includes the following steps: 

# Replacing <pre><pre><code class="XXX"></pre> by <pre>\begin{minted}[bgcolor=bg]{XXX}</pre>