Please note that the recommended version of Scilab is 2025.0.0. This page might be outdated.
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 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:
latex | Scilab extension to write directly LaTeX expression in the help pages |
History
Version | Description |
5.4.0 | Management of tags <note>, <caution>, <warning>, <important> and <tip> |
See Also
- 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
- add_help_chapter — Add an entry in the help list
Report an issue | ||
<< Link toolbox help with Scilab one | Online help management | manedit >> |