User Tools

Site Tools


devel:documentation

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 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"/>
...

Offline documentation

Tutorial materials and help files

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.
  • In Configuration Settings disable edit buttons
    • 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 site exporter 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
  • Some files in lib/images can be removed.
  • Do the following replacements in *.html files of tutorial directory:
    • “../../help/”../../../help/ (more than 40 occurrences);
    • “../../a2a/”../../../help/a2a/ (3 occurrences);
    • “../../overview/”../../../overview/ (just one occurrence).
  • If there are files matching the pattern *.*.* 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.
  • For unknown reason some of the pages may get exported with a wrong style. This results in navigation elements being present in those pages. A possible solution is to export these bad pages individually and copy their html files over.
  • Some icons disappear in offline version. e.g. Wikipedia symbol, most likely due to missing class:
     <a href="http://en.wikipedia..." class="interwiki iw_wp" title="http://en.wikipedia...">...</a> 


    These symbols are stored in lib/images/interwiki directory - do not remove it!

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

This feature requires Workcraft v3.2.3(alpha) or newer.

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

Note that Workcraft runner script is assumed to be in the search path. Otherwise you would have to use the full path.