Scilab Home page | Wiki | Bug tracker | Forge | Mailing list archives | ATOMS | File exchange
Please login or create an account
Change language to: English - Français - Português - 日本語 -
Справка Scilab >> Online help management > 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.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: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>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.
      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 warning 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 role="see-also">
    <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 role="bibliography">
    <title>Bibliography</title>
    <para>
      Add here the function bibliography
    </para>
  </refsection>
  <refsection role="history">
    <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

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)

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:

latexScilab extension to write directly LaTeX expression in the help pages

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

History

ВерсияОписание
5.4.0 Management of tags <note>, <caution>, <warning>, <important> and <tip>
6.0.0 Update the documentation to Docbook 5.1
Scilab Enterprises
Copyright (c) 2011-2017 (Scilab Enterprises)
Copyright (c) 1989-2012 (INRIA)
Copyright (c) 1989-2007 (ENPC)
with contributors
Last updated:
Tue Feb 14 15:13:37 CET 2017