Scilab documentation format 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

A XML file is similar to a HTML file but with a more rigid syntax. The documentation of Scilab must be written using the strict subset of DocBook 5.1 defined in SCI/modules/helptools/schema/scilab.rng. DocBook 5.1 elements are fully documented in "DocBook 5.1: The Definitive Guide"

Scilab is able to understand a large subset of Docbook tags. However, if any are missing, a bug report can be reported on the Scilab bug tracker.

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

    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;refentry xmlns:scilab="http://www.scilab.org" 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"&gt;

Example:

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

    path = help_skeleton('foo', TMPDIR)
    if (isdef('editor') | (funptr('editor')&lt;&gt;0)) then
       editor(path);
    end

Generated foo.xml in TMPDIR:

    &lt;?xml version="1.0" encoding="UTF-8"?&gt;
    &lt;!--
    * Add some comments about XML file
    --&gt;
    &lt;refentry xmlns:scilab="http://www.scilab.org" 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"&gt;
      &lt;refnamediv&gt;
        &lt;refname&gt;foo&lt;/refname&gt;
        &lt;refpurpose&gt;Add short description here. &lt;/refpurpose&gt;
      &lt;/refnamediv&gt;
      &lt;refsynopsisdiv&gt;
        &lt;title&gt;Syntax&lt;/title&gt;
        &lt;synopsis&gt;y = foo(a,b,c)&lt;/synopsis&gt;
      &lt;/refsynopsisdiv&gt;
      &lt;refsection&gt;
        &lt;title&gt;Arguments&lt;/title&gt;
        &lt;variablelist&gt;
          &lt;varlistentry&gt;
            &lt;term&gt;a&lt;/term&gt;
            &lt;listitem&gt;
              &lt;para&gt;
                Add here the input argument description.
              &lt;/para&gt;
            &lt;/listitem&gt;
          &lt;/varlistentry&gt;
          &lt;varlistentry&gt;
            &lt;term&gt;b&lt;/term&gt;
            &lt;listitem&gt;
              &lt;para&gt;
                Add here the input argument description.
              &lt;/para&gt;
            &lt;/listitem&gt;
          &lt;/varlistentry&gt;
          &lt;varlistentry&gt;
            &lt;term&gt;c&lt;/term&gt;
            &lt;listitem&gt;
              &lt;para&gt;
                Add here the input argument description.
              &lt;/para&gt;
            &lt;/listitem&gt;
          &lt;/varlistentry&gt;
          &lt;varlistentry&gt;
            &lt;term&gt;y&lt;/term&gt;
            &lt;listitem&gt;
              &lt;para&gt;
                Add here the output argument description.
              &lt;/para&gt;
            &lt;/listitem&gt;
          &lt;/varlistentry&gt;
        &lt;/variablelist&gt;
      &lt;/refsection&gt;
      &lt;refsection&gt;
        &lt;title&gt;Description&lt;/title&gt;
        &lt;para&gt;
          Add here a paragraph of the function description.
          Other paragraph can be added
        &lt;/para&gt;
        &lt;para&gt;With a latex expression
        &lt;latex&gt;
          \begin{eqnarray}
          f(x,a,r) = \frac{1}{r^{-a}\Gamma(a)} \int_0^x t^{a-1} \exp\left(-rt\right) dt
          \end{eqnarray}
        &lt;/latex&gt;
        &lt;/para&gt;
      &lt;/refsection&gt;
      &lt;refsection&gt;
        &lt;title&gt;More information&lt;/title&gt;
        &lt;note&gt;&lt;para&gt;A note about foo&lt;/para&gt;&lt;/note&gt;
        &lt;caution&gt;&lt;para&gt;A caution about foo&lt;/para&gt;&lt;/caution&gt;
        &lt;warning&gt;&lt;para&gt;A warning about foo&lt;/para&gt;&lt;/warning&gt;
        &lt;important&gt;&lt;para&gt;A important about foo&lt;/para&gt;&lt;/important&gt;
        &lt;tip&gt;&lt;para&gt;A tip about foo&lt;/para&gt;&lt;/tip&gt;
      &lt;/refsection&gt;
      &lt;refsection&gt;
        &lt;title&gt;Examples&lt;/title&gt;
        &lt;programlisting role="example"&gt;&lt;![CDATA[
        Add here scilab instructions and comments
        ]]&gt;&lt;/programlisting&gt;
      &lt;/refsection&gt;
      &lt;refsection role="see-also"&gt;
        &lt;title&gt;See also&lt;/title&gt;
        &lt;simplelist type="inline"&gt;
          &lt;member&gt;
            &lt;link linkend="add a reference name" &gt;add a reference&lt;/link&gt;
          &lt;/member&gt;
          &lt;member&gt;
            &lt;link linkend="add a reference name"&gt;add a reference&lt;/link&gt;
          &lt;/member&gt;
        &lt;/simplelist&gt;
      &lt;/refsection&gt;
      &lt;refsection&gt;
        &lt;title&gt;Authors&lt;/title&gt;
        &lt;simplelist type="vert"&gt;
          &lt;member&gt;add the author name and author reference&lt;/member&gt;
          &lt;member&gt;add another author name and it's reference&lt;/member&gt;
        &lt;/simplelist&gt;
      &lt;/refsection&gt;
      &lt;refsection role="bibliography"&gt;
        &lt;title&gt;Bibliography&lt;/title&gt;
        &lt;para&gt;
          Add here the function bibliography
        &lt;/para&gt;
      &lt;/refsection&gt;
      &lt;refsection role="history"&gt;
        &lt;title&gt;History&lt;/title&gt;
        &lt;revhistory&gt;
          &lt;revision&gt;
            &lt;revnumber&gt;X.Y&lt;/revnumber&gt;
            &lt;revdescription&gt;Function foo added&lt;/revdescription&gt;
          &lt;/revision&gt;
        &lt;/revhistory&gt;
      &lt;/refsection&gt;
      &lt;refsection&gt;
        &lt;title&gt;Used Functions&lt;/title&gt;
        &lt;para&gt;
          Add here the Scilab, C,... used code references
        &lt;/para&gt;
      &lt;/refsection&gt;
    &lt;/refentry&gt;

## How to create a 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.

## List of docbook supported tags

Sectioning and referencing tags:

refentry | A reference page
refsection | A recursive section in a refentry
refsect1 | A recursive section in a refentry level 1 ; similar to `refsection`
refsect2 | A recursive section in a refentry level 2 ; sub-section of `refsect1`
refsect3 | A recursive section in a refentry level 3 ; sub-section of `refsect2`
book | A book
part | A division in a book
chapter | A chapter, as of a book
section | A recursive section
para | A paragraph

Contents types:

refnamediv | The name, purpose, and classification of a reference page
refname | The name of (one of) the subject(s) of a reference page
refpurpose | A short (one sentence) synopsis of the topic of a reference page
refsynopsisdiv | A syntactic synopsis of the subject of the reference page
synopsis | A general-purpose element for representing the syntax of commands or functions
title | The text of the title of a section of a document or of a formal block-level element
informalequation | A displayed mathematical equation without a title
programlisting | A literal listing of all or part of a program
screen | Text that a user sees or might see on a computer screen
caption | A caption
pubdate | The date of publication of a document
bibliomset | A 'cooked' container for related bibliographic information
bibliomixed | An entry in a Bibliography
surname | A family name; in western cultures the 'last name'
firstname | The first name of a person
replaceable | Content that may or must be replaced by the user

Contents styles:

function | The name of a function or subroutine, as in a programming language
varname | The name of a variable
literal | Inline text that is some literal value
emphasis | Emphasized text
subscript | A subscript (as in H2O, the molecular formula for water)
superscript | A superscript (as in x2, the mathematical notation for x multiplied by itself)

Links:

ulink | A link that addresses its target by means of a URL (Uniform Resource Locator)
link | A hypertext link
xref | A cross reference to another part of the document

List tags:

simplelist | An undecorated list of single words or short phrases
member | An element of a simple list
itemizedlist | A list in which each entry is marked with a bullet or other dingbat
orderedlist | A list in which each entry is marked with a sequentially incremented label
listitem | A wrapper for the elements of a list item
variablelist | A list in which each entry is composed of a set of one or more terms and an associated description
term | The word or phrase being defined or described in a variable list
varlistentry | A wrapper for a set of terms and the associated description in a variable list

Table tags:

table | A formal table in a document
informaltable | A table without a title
tbody | A wrapper for the rows of a table or informal table
tr | A row in an HTML table
td | A table entry in an HTML table
th | A table header entry in an HTML table
bgcolor | A HTML attribute for a table, a tr or a td to set the background color

Image tags:

imagedata | Pointer to external image data
imageobject | A wrapper for image data and its associated meta-information
inlinemediaobject | An inline media object (video, audio, image, and so on)
screenshot | A representation of what the user sees or might see on a computer screen
mediaobject | A displayed media object (video, audio, image, etc.)
scilab:image | Any Scilab code into the <scilab:image> foo() <scilab:image> will be executed by an instance of Scilab and the generated graphic included directly into the documentation. This is a Scilab extension of Docbook and is based on the driver/xinit/xend feature.

FAQ tags:

question | A question in a QandASet
answer | An answer to a question posed in a QandASet
qandaentry | A question/answer set within a QandASet
qandaset | A question-and-answer set

History tags:

revhistory | A history of the revisions to a document
revision | An entry describing a single revision in the history of the revisions to a document
revnumber | A document revision number
revremark | A description of a revision to a document
revdescription | A extended description of a revision to a document

Information tags:

note | A message set off from the text
warning | An admonition set off from the text
caution | A note of caution
tip | A suggestion to the user, set off from the text
important | An admonition set off from the text

Scilab specific tag:

latex | Scilab extension to write directly LaTeX expression in the help pages

## See also

- apropos
- help
- help_skeleton
- help_from_sci
- xmltojar
- add_help_chapter

## History

5.4.0 Management of tags <note>, <caution>, <warning>, <important> and <tip>
6.0.0

- Documentation updated to Docbook 5.1
- <refsect1>, <refsect2>, and <refsect3> tags added.
- <td>: valign and style attributes are now supported.
- <th>: align, valign and style attributes are now supported.
- <tr>: valign attribute now supported.

6.0.1

- <imagedata>: id, width, height, align and style attributes are now supported.
- <tr>: id attribute now supported.

6.0.2

- <latex>: attribute alt now supported. Default value is the tag content.
- <tr>: now by default valign="top" instead of "middle".
- For external modules, pages in Farsi or Arabic are now correctly processed to be correctly displayed in a Right-To-Left way in their web version.