====== Preparing the documentation ======

===== Graphics for DokuWiki =====

==== Direct insertion of SVG ====

When inserting SVG images in DokuWiki with //Scalable SVG Insert Plugin// use the following scale factors:
  * STG - 35%
  * PN / FSM / FST / DTD/ WTG - 45%
  * Circuits - 50%

==== SVG to PNG conversion ====
When exporting SVG graphics as PNG in Inkscape for inserting into DokuWiki, use the following DPI settings:
  * STG - 30 dpi
  * PN / FSM / FST / DTD / WTG - 40 dpi
  * Circuits - 45 dpi

==== Screenshot dimensions ====
The maximum screenshot size for DokuWiki should be 900x600. This dimensions of Workcraft window can be set via ''~/.config/workcraft/config.xml'' (note the height is set 28 pixel less to accommodate for the title bar):
<code>
...
<var name="main.maximised" value="false"/>
<var name="main.height" value="572"/>
<var name="main.width" value="900"/>
...
</code>

For fullscreen screenshots the good dimensions seem to be 1900x1000 (minus 28 pixel for the title bar):
<code>
...
<var name="main.maximised" value="false"/>
<var name="main.height" value="972"/>
<var name="main.width" value="1900"/>
...
</code>  

===== Offline documentation =====

==== Tutorial materials and help files ====
We use a tweaked version of ''dokuwiki-light'' template for generating offline pages. See [[:devel:dokuwiki|DokuWiki setup]] for instructions of how to produce this template.

  * Login as ''workcraft'' user to anonymise the generated html files.

  * Disable edit buttons in //Admin->Configuration Settings//:
    * In sections: **maxseclevel=0** (3 by default)
    * In included files: plugin:include:showeditbtn=false (false by default)

  * Temporary modify the content of '':tutorial:feedback'' page (that is included in all tutorials) as follows:
    * Wrap the whole form in ''%%<WRAP hide>%%''.
    * Convert **Feedback** title to code by adding two spaces in front. This is because the headers still propagate to the table of contents even if inside the hidden wrap.

  * Configure exporter in //Admin->Site Export// as follows:
    * Enter your starting Namespace \\ Set Namespace: **help:start** \\ Parent Namespace to export: **(empty)** \\ Export Type:  **all sub namespaces**

    * Select your Options \\ Export Absolute Paths: false \\ Export Body only: false \\ Export Linked Pages: true\\ Disable cache for current request: **true** \\ Export all parameters (e.g. "do"): false \\ Render Engine: (empty) \\ Export Template:  **dokuwiki-light-export** \\ PDF Export: false \\ Numbered Headings: false

    * Select one of the Help Creation Options (optional) \\ all options false

    * Disable (JS/CSS) Plugins while export \\ all options false

  * The site will be exported into siteexport.zip. After downloading and extracting do the following: \\ <code bash>
rm -r  _export  
rm -r lib/scripts
rm -r lib/tpl  
rm -r lib/plugins/acl
rm -r lib/plugins/dw2pdf
rm -r lib/plugins/extensions
rm -r lib/plugins/imagereference
rm -r lib/plugins/include
rm -r lib/plugins/siteexport
rm -r lib/plugins/tag
rm lib/exe/opensearch.html
</code>

  * Preserve ''lib/images/interwiki'' directory as it contains pictograms for Wikipedia references.

  * Some files in lib/images can be removed.
  
  * Do the following replacements in ''*.html'' files of ''help'' directory:
      * ''%%"tutorial/%%'' -> ''%%"../tutorial/%%'' (3 occurrences);
      * ''%%"../overview/%%'' -> ''%%"../../overview/%%'' (1 occurrence).
  
  * Do the following replacements in ''*.html'' files of ''tutorial'' directory:
      * ''%%"../../help/%%'' -> ''%%"../../../help/%%'' (more than 70 occurrences);
      * ''%%"../../a2a/%%'' -> ''%%"../../../help/a2a/%%'' (6 occurrences);
      * ''%%"../../overview/%%'' -> ''%%"../../../overview/%%'' (2 occurrence).

  * If there are files matching the pattern ''*.*.png'' then some of the exported images do not have ''?nolink'' tag. The best option is to correct the corresponding wiki page and export it again. 

==== Handouts ====
The best margins for printout of handouts:
  * top = 14mm
  * bottom = 14mm
  * left = 20mm
  * right = 20mm

SVG diagrams can be reduced up to the following scale:
  * STG - 29%
  * PN / FSM / FST - 38%
  * Circuits - 40%

This is mostly to avoid wide SVG files that do not fit the page width and have side effect on the scale of all the document, including text.

===== Using work files in LyX =====

<WRAP round center 90% important>
This feature requires Workcraft v3.2.3(alpha) or newer. 
</WRAP>

Register Workcraft with Lyx via //Tools->Preferences->File Handling// menu as follows:
  - Add //Work// to the //File Formats// section
    * Format: ''Work''
    * Document format: true
    * Show in export menu: false
    * Vector graphics format: true
    * Short name: ''work''
    * Extension: ''work''
    * MIME: ''application/workcraft''
    * Editor: (Custom) ''workcraft''
    * Viewer: (Custom) ''workcraft''
  - Add //Work -> SVG// to the //Converters// section
    * From format: ''Work''
    * To format: ''SVG''
    * Converter: ''%%workcraft -nogui -dir:$$p -exec:"exportSvg(load(args[0]), args[1]); exit();" $$i $$o%%''

<WRAP info round center 90%>
Note that Workcraft runner script is assumed to be in the search path. Otherwise you would have to use the full path.
</WRAP>