Scilab Home page | Wiki | Bug tracker | Forge | Mailing list archives | ATOMS | File exchange
Please login or create an account
Change language to: English - Português - Русский - 日本語

Please note that the recommended version of Scilab is 6.0.0. This page might be outdated.
See the recommended documentation of this function

Aide de Scilab >> Gestion de l'aide en ligne > Scilab documentation format

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 defined in SCI/modules/helptools/schema/scilab.rnc. DocBook 5 elements are fully documented in "DocBook 5.0: 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".

<?xml version="1.0" encoding="UTF-8"?>
<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">

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 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">
  <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>Arguments</title>
    <variablelist>
      <varlistentry>
        <term>a</term>
        <listitem>
          <para>
            Add here the input argument description.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>b</term>
        <listitem>
          <para>
            Add here the input argument description.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>c</term>
        <listitem>
          <para>
            Add here the input argument description.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>y</term>
        <listitem>
          <para>
            Add here the output argument 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>
    <para>With a latex expression
    <latex>
      \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}
    </latex>
    </para>
  </refsection>
  <refsection>
    <title>More information</title>
    <note><para>A note about foo</para></note>
    <caution><para>A caution about foo</para></caution>
    <warning><para>A warsning about foo</para></warning>
    <important><para>A important about foo</para></important>
    <tip><para>A tip about foo</para></tip>
  </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>History</title>
    <revhistory>
      <revision>
        <revnumber>X.Y</revnumber>
        <revdescription>Function foo added</revdescription>
      </revision>
    </revhistory>
  </refsection>
  <refsection>
    <title>Used Functions</title>
    <para>
      Add here the Scilab, C,... used code references
    </para>
  </refsection>
</refentry>

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

Generic tags

refentry A reference page
section A recursive section
book A book
part A division in a book
chapter A chapter, as of a book
title The text of the title of a section of a document or of a formal block-level element
para A paragraph
literal Inline text that is some literal value
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
refsection A recursive section in a refentry
programlisting A literal listing of all or part of a program
screen Text that a user sees or might see on a computer screen
pubdate The date of publication of a document
link A hypertext link
ulink A link that addresses its target by means of a URL (Uniform Resource Locator)
xref A cross reference to another part of the document
term The word or phrase being defined or described in a variable list
emphasis Emphasized text
informalequation A displayed mathematical equation without a title
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)
replaceable Content that may or must be replaced by the user
caption A caption
surname A family name; in western cultures the 'last name'
firstname The first name of a person
bibliomset A 'cooked' container for related bibliographic information
bibliomixed An entry in a Bibliography

List tags:

simplelist An undecorated list of single words or short phrases
member An element of a simple list
listitem A wrapper for the elements of a list item
varlistentry A wrapper for a set of terms and the associated description in a variable list
variablelist A list in which each entry is composed of a set of one or more terms and an associated description
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

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:

latexScilab extension to write directly LaTeX expression in the help pages

History

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

See Also

  • apropos — recherche d'un mot-clé dans l'aide de Scilab
  • help — commande d'aide en ligne
  • help_skeleton — build the skeleton of the xml help file associated to a Scilab function
  • help_from_sci — Generate help files and demo files from the head comments section of a .sci source file.
  • xmltojar — converts xml Scilab help files to javaHelp format
  • add_help_chapter — Add an entry in the help list
Scilab Enterprises
Copyright (c) 2011-2017 (Scilab Enterprises)
Copyright (c) 1989-2012 (INRIA)
Copyright (c) 1989-2007 (ENPC)
with contributors
Last updated:
Thu Oct 02 13:54:44 CEST 2014