# doc_kit, a toolkit for Scilab documentation writers

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

## Installation

This toolkit already includes all the needed software components (Saxon, FOP, Batik, JEuclid, JavaHelp, Jing, etc), therefore you just need to install a JavaTM Development Kit (JDK) 1.5+ in order to be able to run the command-line 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`.

1. Unzip the distribution somewhere. This creates a `doc_kit/` directory.

       C:\> unzip doc_kit.zip
       C:\> dir
       ...
       13/02/2008  14:19    <DIR>          doc_kit
       ...

2. All the command-line tools are found in the `bin/` subdirectory.

       C:\doc_kit> cd bin
       C:\doc_kit\bin> dir /w
       ...
       [.]               [..]              man2sci           sci2jh
       sciviewhelp       sci2html          manrev2sci        scivalid
       scivalid.bat      manrev2sci.bat    man2sci.bat       sci2html.bat
       sciviewhelp.bat   sci2pdf.bat       sci2pdf           sci2jh.bat
       sci2chm.bat
       ...

   All the above command-line tools are intended to be used directly from the `doc_kit/bin/` subdirectory.

3. Test your installation by converting this document (`doc_kit/doc/doc.xml`) to a JavaHelp `.jar` file.

   1. First make sure that the Java tools are actually in your `PATH`.

          C:\doc_kit\bin> java -version
          java version "1.6.0_04"
          Java(TM) SE Runtime Environment (build 1.6.0_04-b12)
          Java HotSpot(TM) Client VM (build 10.0-b19, mixed mode, sharing)

          C:\doc_kit\bin> jar
          Usage: jar {ctxui}[vfm0Me] ...

   2. Convert this document (`doc_kit/doc/doc.xml`) to JavaHelp using the `sci2jh` command-line tool.

          C:\doc_kit\bin> sci2jh ..\doc\doc.xml C:\tmp\test_help.jar

      Note that the generated JavaHelp file must end with "`_help.jar`" and not just with "`.jar`".

   3. Preview the contents of the generated `.jar` file using the `sciviewhelp` tool.

          C:\doc_kit\bin> sciviewhelp C:\tmp\test_help.jar

## Contents of the distribution

bin/

  Contains the command-line tools: shell scripts for use on Unix/Linux/Mac OS X and `.bat` files for use on Windows (2000, XP, Vista).

css/

  Contains the CSS style sheets which are used to customize the look of the HTML pages generated by `sci2html`, `sci2chm` and `sci2jh`.

doc/

  Contains this document in various formats.

docbook_xsl/

  Contains a copy of the DocBook XSL style sheets. These style sheets are used to convert DocBook 5 documents (and hence, Scilab documentation) to HTML, PostScript, PDF, JavaHelp, etc.

legal/

  Contains a README and a LICENSE file for each software component bundled with this toolkit.

lib/

  Contains all the software components (that is, Java class libraries packaged as `.jar` files) bundled with this toolkit.

schema/

  Contains `scilab.rnc`, the RELAX NG schema defining the DocBook 5 subset used for the documentation of Scilab.

src/

  Contains the source code of two utility classes needed by the command-line tools of this toolkit. More information in "Recompiling the sources".

xsl/
  convert/manrev2sci.xsl

    The XSLT style sheet used to convert a document conforming to `manrev.dtd` to a document conforming to the DocBook 5 subset.

  convert/man2manrevxsl

    The XSLT style sheet used to convert a document conforming to `man.dtd` to a document conforming to `manrev.dtd`.

  fo/docbook.xsl

    Fixes bugs in the stock `docbook/fo/htmltbl.xsl`.

## The Scilab subset of DocBook 5

The documentation of Scilab must be written using the strict subset of DocBook 5 defined in `doc_kit/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`

## 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`

## Recompiling the sources

Directory `doc_kit/src/org/scilab/doc_kit/` contains the source code of two utility classes needed by some of the above command-line tools:

HelpViewer.java

  The source code of `sciviewhelp`.

CopyConvert.java

  A preprocessor used as the first pass in `sci2html`, `sci2chm`, `sci2jh` and `sci2pdf`.

  This preprocessor:

  - Creates a ``flat' (entity references are expanded; XIncludes are not supported) copy of the XML document to be transformed.

  - If the source document contains an embedded MathML element (`imagedata/mml:math`), this element is extracted to a temporary file, then the temporary file is converted to a PNG image by the means of JEuclid. After doing this, the original `imagedata/mml:math` found in the source is replaced in the flat XML document by an `imagedata` element pointing to the generated PNG file (`imagedata/@fileref`).

  - Same for embedded SVG elements which are converted to PNG images by the means of Batik.

  - If the source document contains an `imagedata` element pointing to a MathML file (filename extension is "`.mml`"), this file is converted to PNG by the means of JEuclid. After doing that, the `imagedata` element contained in the flat XML document is made to point to the `.png` file rather than to the `.mml` file.

  - Same for `imagedata` elements pointing to SVG files (filename extension is "`.svg`" or "`.svgz`"), but in this case, it is Batik which is used to perform the conversion.

  - Same for `imagedata` elements pointing to "`.tex`" files (assumed to contain math equations), but in this case, it is TEX+Ghostscript which are used to perform the conversion.

    The `CopyConvert` preprocessor searches the following programs in the `PATH`: `latex`, `dvips`, `gs` on Unix/`gswin32c` on Windows, `ps2pdf`.

The above sources may be recompiled by running ant in the `doc_kit/src/` directory:

    C:\doc_kit/src> dir /w
    ...
    build.xml   [org]       [class]
    ...
    C:\doc_kit/src> ant
    Buildfile: build.xml

    init:

    compile:
    ...

Doing this rebuilds `sci_doc_kit.jar` in `doc_kit/lib/`.

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

  This Scilab configuration is available as an add-on. This add-on may be downloaded and installed directly within XMLmind XML Editor using menu item Options|Install Add-ons. But before being able to do that, you must specify where to find such add-on. Fortunately this is done once for all:

  1. Use menu item Options|Preferences.

  2. Click on the "Install Add-ons" item in the left pane.

  3. Click the Add button found at the right of the "Download add-ons from these servers" list.

  4. Specify the following URL "`http://www.scilab.org/download/scilab_config.xxe_addon`" when prompted, then click OK.

  5. Click OK to close the Preferences dialog box.

  From now, you can use menu item Options|Install Add-ons and select the add-on called "A configuration for the Scilab subset of DocBook 5" from the list of all available add-ons.