Scilab Home page | Wiki | Bug tracker | Forge | Mailing list archives | ATOMS | File exchange
Change language to: English - Français - Português - 日本語 -

See the recommended documentation of this function

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

<?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: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"?>
<!--
-->
<refentry xmlns:scilab="http://www.scilab.org" xml:id="foo" xml:lang="en"
xmlns="http://docbook.org/ns/docbook"
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>
</refnamediv>
<refsynopsisdiv>
<title>Syntax</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.
</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>
</refsection>
<refsection>
<title>Examples</title>
<programlisting role="example"><![CDATA[
]]></programlisting>
</refsection>
<refsection role="see-also">
<simplelist type="inline">
<member>
</member>
<member>
</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 role="bibliography">
<title>Bibliography</title>
<para>
</para>
</refsection>
<refsection role="history">
<title>History</title>
<revhistory>
<revision>
<revnumber>X.Y</revnumber>
</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

Sectionning 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)

 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 foo() 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

• apropos — searches keywords in Scilab help
• help — on-line help command
• 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

### History

 Версия Описание 5.4.0 Management of tags , , , and 6.0.0 Update the documentation to Docbook 5.1