man

on line help XML file description format

Description

The on line help source files are written in XML.

Source files (with extension .xml) can be found in the <SCIDIR>/modules/<MODULE NAME>/help/<language>/* directories. The file name is usually associated to a keyword (corresponding to a function name most of the cases) it describes.

A few words about XML

An XML file resembles to an HTML file but with a more rigid syntax. 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"

How to write a simple xml scilab help page:

If one want to write the xml file associated to a new scilab function he or she may use the Scilab function help_skeleton to produce the skeleton of the xml file. In most cases the user will not be required to know xml syntax.

How to write a simple xml scilab help page: an example

The root element of a document which conforms to the Scilab DocBook 5 subset must have version attribute set to "5.0-subset Scilab".

<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0-subset Scilab" xml:id="foo" xml:lang="en"
 xmlns="http://docbook.org/ns/docbook"
 xmlns:xlink="http://www.w3.org/1999/xlink"
 xmlns:svg="http://www.w3.org/2000/svg"
 xmlns:ns4="http://www.w3.org/1999/xhtml"
 xmlns:mml="http://www.w3.org/1998/Math/MathML"
 xmlns:db="http://docbook.org/ns/docbook">

Example:

function y=foo(a, b, c)
  y = a + 2 * b + c;
endfunction

path = help_skeleton('foo', TMPDIR)
if (isdef('editor') | (funptr('editor')<>0)) then
  editor(path);
end

Generated foo.xml in TMPDIR:

<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Add some comments about XML file
-->
<refentry version="5.0-subset Scilab" xml:id="foo" xml:lang="en"
 xmlns="http://docbook.org/ns/docbook"
 xmlns:xlink="http://www.w3.org/1999/xlink"
 xmlns:svg="http://www.w3.org/2000/svg"
 xmlns:ns4="http://www.w3.org/1999/xhtml"
 xmlns:mml="http://www.w3.org/1998/Math/MathML"
 xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <pubdate>$LastChangedDate: 29-11-2010 $</pubdate>
  </info>
  <refnamediv>
    <refname>foo</refname>
    <refpurpose>Add short description here. </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <title>Calling Sequence</title>
    <synopsis>y = foo(a,b,c)</synopsis>
  </refsynopsisdiv>
  <refsection>
    <title>Parameters</title>
    <variablelist>
      <varlistentry>
        <term>a</term>
        <listitem>
          <para>
            Add here the parameter description.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>b</term>
        <listitem>
          <para>
            Add here the parameter description.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>c</term>
        <listitem>
          <para>
            Add here the parameter description.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>y</term>
        <listitem>
          <para>
            Add here the parameter description.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>
  <refsection>
    <title>Description</title>
    <para>
          Add here a paragraph of the function description. 
          Other paragraph can be added 
    </para>
  </refsection>
  <refsection>
    <title>Examples</title>
    <programlisting role="example"><![CDATA[
        Add here scilab instructions and comments
    ]]></programlisting>
  </refsection>
  <refsection>
    <title>See Also</title>
    <simplelist type="inline">
      <member>
        <link linkend="add a reference name" >add a reference</link>
      </member>
      <member>
        <link linkend="add a reference name">add a reference</link>
      </member>
    </simplelist>
  </refsection>
  <refsection>
    <title>Authors</title>
    <simplelist type="vert">
      <member>add the author name and author reference</member>
      <member>add another author name and it's reference</member>
    </simplelist>
  </refsection>
  <refsection>
     <title>Bibliography</title>
       <para>
         Add here the function bibliography
       </para>
     </refsection>
  <refsection>
     <title>Used Functions</title>
       <para>
         Add here the Scilab, C,... used code references
       </para>
     </refsection>
</refentry>

How to create an help chapter

Create a directory and write down a set of xml files build as described above. Then start Scilab and execute xmltojar (see xmltojar for more details) .

How to make Scilab know a new help chapter

This can be done by the function add_help_chapter.