Documentation Strategy » History » Revision 20
Revision 19 (Detlef Hühnlein, 10/17/2012 12:03 PM) → Revision 20/21 (Detlef Hühnlein, 10/17/2012 12:55 PM)
h1. Document Creation Process
In order to allow distributed and convenient editing using the wiki *AND* producing documents with high quality typesetting, the document creation process as depicted in the following figure is implemented.
!process.png(Document Creation Process)!
h2. Editing in Wiki
The primary editing is performed in the present Wiki, which uses the "Textile":http://en.wikipedia.org/wiki/Textile_%28markup_language%29 markup as explained "here":http://www.redmine.org/projects/redmine/wiki/RedmineTextFormatting.
In order to allow an automated conversion to and processing with LaTeX, the following issues MUST be considered:
# Each Wiki-page is converted to a corresponding .tex file
# h1.-h3. correspond to \section{ }-\subsubsection{ }
# References to literature MAY be included, but they MUST be 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. Export
The export of the Textile source to an appropriate .tex file and the provision of embedded pictures MAY be performed manually.
In the long turn there SHOULD be an automated export of the Wiki-pages as explained "here":http://stbuehler.de/blog/article/2011/06/04/exporting_redmine_wiki_pages.html for example.
h2. Textile to LaTeX conversion
The Textile-markup from the Wiki can be converted to LaTeX using "RedCloth":http://redcloth.org/.
h2. LaTeX-Post-Processing
In order to support references to documents (e.g. "[BSI-TR-03112-7]":http://docs.ecsec.de/BSI-TR-03112-7), intra-Wiki-Links and the inclusion of pretty-printed XML- or Java-code, the raw LaTeX document needs to be cleaned up with "awk":https://de.wikipedia.org/wiki/Awk for example.
This includes the following replacements:
<pre><code>1. <pre><code class="XXX"> --> \begin{minted}[bgcolor=bg]{XXX}
2. </code></pre> --> \end{minted}
3. "[LABEL]":http://url --> \cite{LABEL}
4. [[WikiRef]] --> Inserting canonical labels {file+headline} and converting Intra-Wiki-links to \ref{ }
</code></pre>
h2. Document Compilation
Finally the LaTeX sources are compiled to produce a nice pdf-document for example.
h1. Document Landscape
The following documents are envisioned:
* [[Software Architecture]] - -- contains a description of the software architecture of the Open eCard App
* [[Developer Guide]] - -- contains everything a developer needs to know
* [[Build Management System]] - contains a description of the Open eCard build management system
* [[Quality Manual]] - -- specifies all quality related aspects
* [[User Guide]] - contains everything a user of the Open eCard App needs to know
* [[Integrator Guide]] - -- contains everything an integrator needs to know