doc_kit, a toolkit for Scilab documentation writers
Contents
Chapter 1. Introduction
This toolkit contains all the command-line tools needed to write some documentation for Scilab.
As of version 5, Scilab uses a strict subset of DocBook 5 for all its documentation. This toolkit also contains tools (manrev2sci and man2sci) which may be used to convert from Scilab's old formats (manrev.dtd and man.dtd) to the new one.
Chapter 2. Installation
This toolkit already includes all the needed software components :
Therefore you just need to install a JavaTM Development Kit (JDK) 1.5+ in order to be able to run the commandline tools.
Note that installing a Java runtime (JRE) is insufficient because some command-line tools expect to have the jar utility (part of the JDK, not part of the JRE) in the PATH.
All the command-line tools are found in the SCI/modules/helptools/bin subdirectory :
man2sci sci2jh sciviewhelp sci2html manrev2sci scivalid scivalid.bat manrev2sci.bat man2sci.bat sci2html.bat sciviewhelp.bat sci2pdf.bat sci2pdf sci2jh.bat sci2chm.bat
Chapter 3. The Scilab subset of DocBook 5
The documentation of Scilab must be written using the strict subset of DocBook 5 defined in SCI/modules/helptools/schema/scilab.rnc. DocBook 5 elements are fully documented in "DocBook 5.0 : The Definitive Guide", therefore there is not much to add here.
Important
The root element of a document which conforms to the Scilab DocBook 5 subset must have version attribute set to "5.0-subset Scilab".
Example:
<?xml version="1.0" encoding="UTF-8" ?> <refentry version="5.0-subset Scilab" xmlns="http://docbook.org/ns/docbook" ...
The subset comprises the following elements:
- book and its divisions:
- part, partintro
- reference
- chapter, section
- appendix
- Meta-info elements: info, title, author, personname, affiliation, jobtitle, orgname, pubdate, keywordset, keyword.
refentry (the DocBook equivalent of a man page) and its divisions: refnamediv, refname, refpurpose, refsynopsisdiv, synopsis, refsection.
- Displayed elements:
- figure, mediaobject, imageobject, imagedata (having either a fileref attribute or embedding MathML or SVG)
- example
- note
- equation, informalequation
- table (HTML tables only, that is, not CALS tables), caption, informaltable, col, colgroup, tbody, thead, tfoot, tr, td, th
- Other block-level elements:
- itemizedlist, orderedlist, listitem
- variablelist, varlistentry, term
- simplelist, member
- para
- programlisting
- Inline-level elements:
- emphasis, literal
- phrase, replaceable,
- subscript, superscript
- link
- indexterm, primary
- inlinemediaobject
- inlineequation
Chapter 4. The command-line tools
All command-line tools are self-documented. Simply execute the command without any argument to display a short help text.
Example:
C:\doc_kit\bin> sciviewhelp Usage: sciviewhelp javahelp_jar_file ... javahelp_jar_file Allows to browse the contents of one or more JavaHelp[tm] .jar files created using sci2jh. The name of a JavaHelp .jar file must end with '_help.jar'.
man2sci, man2sci.bat
Converts a document conforming to man.dtd to a document conforming to scilab.rnc. Usage: man2sci in_man_xml_file out_scilab_xml_file
manrev2sci, manrev2sci.bat
Converts a document conforming to manrev.dtd to a document conforming to scilab.rnc. Usage: manrev2sci in_manrev_xml_file out_scilab_xml_file
sci2html, sci2html.bat
Converts an XML document conforming to scilab.rnc to multi-page HTML. Usage: sci2html in_xml_file out_html_directory
sci2chm.bat
Converts an XML document conforming to scilab.rnc to a Windows HTML Help (".chm") file. Not available on platforms other than Windows. By default, this script assumes that hhc.exe is found in "C:\Program Files\HTML Help Workshop\hhc.exe". If this is not the case, please modify the "hhc" variable found at the beginning of the ".bat" file. Usage: sci2chm in_xml_file out_chm_file
sci2jh, sci2jh.bat
Converts an XML document conforming to scilab.rnc to a JavaHelp .jar file. out_javahelp_jar_file must end with "_help.jar". Usage: sci2jh in_xml_file out_javahelp_jar_file
sci2pdf, sci2pdf.bat
Converts an XML document conforming to scilab.rnc to PDF or to PostScript. A PostScript file is generated if out_pdf_or_ps_file ends with ".ps". Usage: sci2pdf in_xml_file out_pdf_or_ps_file
scivalid, scivalid.bat
Validates specified XML files against the scilab.rnc schema. Usage: scivalid xml_file ... xml_file
sciviewhelp, sciviewhelp.bat
Allows to browse the contents of one or more JavaHelp .jar files created using sci2jh. The name of a JavaHelp .jar file must end with "_help.jar". Usage: sciviewhelp javahelp_jar_file ... javahelp_jar_file
Chapter 5. Companion tools
- Inkscape, an excellent drawing tool natively supporting SVG.
- MiKTeX, an excellent TEX distribution for Windows.
XMLmind XML Editor, a visual XML editor with built-in support for DocBook 5. There are many fine XML editors but this one
- has a free Personal Edition allowing to use it to create documentation for Open Source projects such as Scilab,
has a configuration specially designed to support the Scilab DocBook 5 subset.
Install scilab configuration add-on (XXE 4)
Download the xxe_scilab_config-1.1.0.zip file
- Unzip the downloaded distribution in the addon/ subdirectory of XXE user preferences directory. XXE user preferences directory is:
$$HOME/.xxe4/ on Linux,
$$HOME/Library/Application Support/XMLmind/XMLEditor4/ on the Mac,
%APPDATA%\XMLmind\XMLEditor4\ on Windows 2000, XP, Vista.Example: C:\Documents and Settings\john\Application Data\XMLmind\XMLEditor4\ on Windows 2000 and XP. C:\Users\john\AppData\Roaming\XMLmind\XMLEditor4\ on Windows Vista.
Chapter 6. XML examples
Image inclusion
<refsection>
<title>Example of image inclusion</title>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="../images/plot3d.png"/>
</imageobject>
</inlinemediaobject>
</para>
</refsection>
MathML inclusion : Separate file
<refsection>
<title>Exemple d'inclusion de MathML</title>
<para>
<informalequation>
<mediaobject>
<imageobject>
<imagedata align="center" fileref="../mml/quadratic.mml" />
</imageobject>
</mediaobject>
</informalequation>
</para>
</refsection>
MathML inclusion : Inline
<refsection>
<title>Example of MathML inclusion : Inline</title>
<para>
<informalequation>
<mediaobject>
<imageobject>
<imagedata>
<mml:math>
<mml:semantics>
<mml:mrow>
<mml:mrow>
<mml:mfenced mml:close="∣" mml:open="∣">
<mml:msub>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mrow>
<mml:mi>z</mml:mi>
<mml:mrow>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mi>v</mml:mi>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
<mml:mo mml:stretchy="false">−</mml:mo>
<mml:mi>z</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mi>u</mml:mi>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
</mml:mrow>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
<mml:mrow>
<mml:mi mml:fontstyle="italic">ltol</mml:mi>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mi>j</mml:mi>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
</mml:mrow>
</mml:msub>
</mml:mfenced>
<mml:mo mml:stretchy="false">≤</mml:mo>
<mml:mi mml:fontstyle="italic">tol</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:mrow>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mi>j</mml:mi>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
<mml:mo mml:stretchy="false">⋅</mml:mo>
<mml:mfenced mml:close="∣" mml:open="∣">
<mml:msub>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mrow>
<mml:mi>z</mml:mi>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mi>u</mml:mi>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
</mml:mrow>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
<mml:mrow>
<mml:mi mml:fontstyle="italic">ltol</mml:mi>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mi>j</mml:mi>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
</mml:mrow>
</mml:msub>
</mml:mfenced>
</mml:mrow>
<mml:mo mml:stretchy="false">+</mml:mo>
<mml:mi mml:fontstyle="italic">tol</mml:mi>
</mml:mrow>
<mml:mrow>
<mml:mo mml:stretchy="false">(</mml:mo>
<mml:mi>j</mml:mi>
<mml:mo mml:stretchy="false">)</mml:mo>
</mml:mrow>
<mml:mi>,</mml:mi>
<mml:mi mml:fontstyle="normal">for</mml:mi>
<mml:mrow>
<mml:mi>j</mml:mi>
<mml:mo mml:stretchy="false">=</mml:mo>
<mml:mn>1</mml:mn>
</mml:mrow>
<mml:mi mml:fontstyle="normal">:</mml:mi>
<mml:mi mml:fontstyle="normal">ntol</mml:mi>
</mml:mrow>
<mml:annotation
mml:encoding="StarMath 5.0">abs(z(v)-z(u))_{ltol(j)}
<= tol(j) cdot abs(z(u))_{ltol(j)} + tol(j), for
j=1:ntol</mml:annotation>
</mml:semantics>
</mml:math>
</imagedata>
</imageobject>
</mediaobject>
</informalequation>
</para>
</refsection>