doc_kit, a toolkit for Scilab documentation writers

Contents

doc_kit, a toolkit for Scilab documentation writers

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:

   1 <xml version="1.0" encoding="UTF8" >
   2 <refentry version="5.0subset Scilab"
   3 xmlns="http//docbook.org/ns/docbook"
   4 ...

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.

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:

Use menu item Options|Preferences.
Click on the "Install Add-ons" item in the left pane.
Click the Add button found at the right of the "Download add-ons from these servers" list.
Specify the following URL "http://www.scilab.org/download/xxe/scilab_config.xxe_addon" when prompted, then click OK.
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.