doc_kit, a toolkit for Scilab documentation writers

/!\ Many items on this page are deprecated.

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:

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

Install scilab configuration add-on (XXE 4)

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>

quadratic.mml

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)}
                  &lt;= 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>

public: howto/scilab documentation kit (last edited 2011-03-30 16:18:07 by localhost)