on line help XML file description format
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.
An XML file resembles 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.
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.
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 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>
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) .
This can be done by the function add_help_chapter.
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 H 2 O, the molecular formula for water) superscript A superscript (as in x 2 , 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
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.)
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 proprietary tag to write directly LaTeX expression in the help pages
Version Description 5.4.0 Management of tags <note>, <caution>, <warning>, <important> and <tip>