Preparing the documentation

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%

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

The maximum screenshot size for DokuWiki should be 900×600. 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):

...
<var name="main.maximised" value="false"/>
<var name="main.height" value="572"/>
<var name="main.width" value="900"/>
...

For fullscreen screenshots the good dimensions seem to be 1900×1000 (minus 28 pixel for the title bar):

...
<var name="main.maximised" value="false"/>
<var name="main.height" value="972"/>
<var name="main.width" value="1900"/>
...

We use a tweaked version of dokuwiki-light template for generating offline pages. See 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:
  

  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

• 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.

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.

Register Workcraft with Lyx via Tools→Preferences→File Handling menu as follows:

1. 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
2. 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