add CDATA + role in the helptools module
[scilab.git] / scilab / modules / helptools / help / en_US / man.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en" xml:id="man">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>man</refname>
19     <refpurpose> on line help XML file description format</refpurpose>
20   </refnamediv>
21   <refsection>
22     <title>Description</title>
23     <para>
24     The on line help source files are written in XML.
25   </para>
26     <para>
27     Source files (with extension .xml) can be found in the
28     <literal>&lt;SCIDIR&gt;/man/&lt;language&gt;/*</literal> directories. The file name is usually
29     associated to a keyword (corresponding to a function name most of the cases) it describes.
30   </para>
31   </refsection>
32   <refsection>
33     <title>A few words about XML</title>
34     <para>An XML file resembles to an HTML file but with both a more rigid and free syntax.
35      Free because you may build your own tags: the set of tags together with its rules
36      must be described somewhere, generally in another file (<literal>&lt;SCIDIR&gt;/man/manrev.dtd</literal> 
37      for scilab),
38      and rigid because, once the tags and rules are defined (which are called the Definition
39      Type Document: DTD) , you must respect its (in particular to every open tags 
40      <literal>&lt;MY_TAG&gt;</literal> must correspond a closed  <literal>&lt;/MY_TAG&gt;</literal>).</para>
41     <para> 
42      The DTD manrev.dtd is written in SGML and precises the exact syntax required by a 
43      scilab XML help page. So if you know this language you may red this file. 
44      The following annotated example (see the next section) shows you some possibilities 
45      offered by this DTD and may be enough to write simple help pages.
46      </para>
47     <para>
48      Once an XML page is written and conforms to the DTD, it may be transformed in
49      HTML to be red by your favorite browser or by the tcltk scilab browser
50      (see section browser choice in this page). The XML -&gt; HTML translation is controled
51      by a set of rules written in the (XML) file <literal>&lt;SCIDIR&gt;/man/language/html.xsl</literal>.
52      Those rules are currently more or less restricted to fit the tcltk scilab browser
53      features (which may display correctly only basic HTML): if you use a real HTML
54      browser and want a better appearance you have to modify this file.
55      </para>
56   </refsection>
57   <refsection>
58     <title>How to write a simple xml scilab help page: the lazzy way</title>
59     <para>
60          If one want to write the xml file associated to a new scilab function
61         he or she may use the Scilab function <link linkend="help_skeleton">help_skeleton</link> to produce
62         the skeleton of the xml file. In most cases the user will not be
63         required to know xml syntax. 
64        </para>
65   </refsection>
66   <refsection>
67     <title>How to write a simple xml scilab help page: an example</title>
68     <para>
69      Here is a simple annotated XML scilab help page which describes an hypothetic foo scilab
70      function. In the following, the XML file is displayed in a <literal>type writer font</literal>
71      and cut-out in several parts, each part being preceded by some associated explanations.
72      The entire XML file <literal>foo.xml</literal> is in the <literal>&lt;SCIDIR&gt;/man/eng/utility</literal>
73      directory and the result may be displayed by clicking on <link linkend="foo">foo</link>.
74      (you may found others examples in the <literal>&lt;SCIDIR&gt;/examples/man-examples-xml</literal> 
75      directory). <emphasis role="bold">Finally</emphasis> note that some tag pairs <literal>&lt;TAG&gt;</literal>, 
76      <literal>&lt;/TAG&gt;</literal> have been renamed here <literal>&lt;ATAG&gt;</literal>, 
77      <literal>&lt;/ATAG&gt;</literal>. This is because some scilab scripts which do some work
78      on or from the xml files don't verify if a tag is inside a <literal>VERBATIM</literal> entry.
79      </para>
80     <para>
81       The 3 first lines of the file are mandatory, the second precises the path to the
82       DTD file and the third, formed by the <literal>&lt;MAN&gt;</literal> tag, begin the 
83       hierarchical description (the file must finish with the <literal>&lt;/MAN&gt;</literal> tag). 
84       The 4 followings entries : <literal>LANGUAGE</literal>, <literal>TITLE</literal>, 
85       <literal>TYPE</literal> and  <literal>DATE</literal>, are also mandatory (in this order) the text 
86       corresponding to  <literal>&lt;TYPE&gt;</literal> being generally 'Scilab function' 
87       (most of the cases) but may be simply  'Scilab keyword' or 'Scilab data type', ..., 
88       depending of what explains the help page. 
89    </para>
90     <programlisting><![CDATA[ 
91 <!DOCTYPE MAN SYSTEM "<SCIDIR>/man/manrev.dtd">
92 <MAN>
93    <LANGUAGE>eng</LANGUAGE>
94    <TITLE>foo</TITLE>
95    <TYPE>Scilab function</TYPE>
96    <DATE>$LastChangedDate$</DATE>
97  ]]></programlisting>
98     <para>
99    The first of these 2 following entries (<literal>SHORT_DESCRIPTION</literal>)
100    is mandatory and important since the words of the short description text, are used by the
101    <link linkend="apropos">apropos</link> command to search help pages from a keyword: the short description
102    is used to build the <literal>whatis.html</literal> file corresponding to your toolbox and 
103    the <literal>apropos keyword</literal> command looks in all the whatis files and then proposes
104    the links to every page containing the word <literal>keyword</literal> in its  short description
105    (in fact the actual associated tags are <literal>&lt;SHORT_DESCRIPTION&gt;</literal> and 
106    <literal>&lt;/SHORT_DESCRIPTION&gt;</literal> and not <literal>&lt;ASHORT_DESCRIPTION&gt;</literal>
107    and <literal>&lt;/ASHORT_DESCRIPTION&gt;</literal>).
108    The next entry (<literal>CALLING_SEQUENCE</literal>) must be used if you describe a function 
109    (but is not strictly mandatory). If your function have several calling sequences
110    use several <literal>CALLING_SEQUENCE_ITEM</literal> entries.
111    </para>
112     <programlisting><![CDATA[
113
114           <ASHORT_DESCRIPTION name="foo">foo short description</ASHORT_DESCRIPTION>
115           <CALLING_SEQUENCE>
116               <CALLING_SEQUENCE_ITEM>[y] = foo(x)</CALLING_SEQUENCE_ITEM>
117           </CALLING_SEQUENCE>
118    
119         ]]></programlisting>
120     <para>
121    The following entry (<literal>PARAM</literal>) is not strictly mandatory but is
122    the good one to describe each parameters (input and output) in case of a function.
123    </para>
124     <programlisting><![CDATA[
125
126           <PARAM>
127              <PARAM_INDENT>
128                 <PARAM_ITEM>
129                    <PARAM_NAME>x</PARAM_NAME>
130                    <PARAM_DESCRIPTION>
131                       <SP>: what may be x</SP>
132                    </PARAM_DESCRIPTION> 
133                 </PARAM_ITEM>
134                 <PARAM_ITEM>
135                    <PARAM_NAME>y</PARAM_NAME>
136                    <PARAM_DESCRIPTION>
137                       <SP>: what may be y</SP>
138                    </PARAM_DESCRIPTION> 
139                 </PARAM_ITEM>
140              </PARAM_INDENT>
141           </PARAM>
142    
143         ]]></programlisting>
144     <para>
145    The <literal>DESCRIPTION</literal> entry is perhaps the most significant one (but not strictly 
146    mandatory) and may be more sophisticated than in this example (for instance you may have    
147    <literal>DESCRIPTION_ITEM</literal> sub-entries). Here you see how to write several paragraphes
148    (each one enclosed between the <literal>&lt;P&gt;</literal> and <literal>&lt;/P&gt;</literal> tags),
149    how to emphasis a variable or a function name (by enclosing it between the 
150    <literal>&lt;VERB&gt;</literal> and <literal>&lt;/VERB&gt;</literal> tags), how to
151    emphasis a part of text (<literal>&lt;EM&gt;</literal> or <literal>&lt;BD&gt;</literal>
152    and <literal>&lt;TT&gt;</literal> to put it in a type writer font)), and finally, how to put a link onto 
153    another help page  (in fact the actual associated tags are <literal>&lt;LINK&gt;</literal> and 
154    <literal>&lt;/LINK&gt;</literal> and not <literal>&lt;ALINK&gt;</literal>
155    and <literal>&lt;/ALINK&gt;</literal>).
156    </para>
157     <programlisting><![CDATA[
158
159          <DESCRIPTION>
160              <P>
161                 A first paragraph which explains what computes the foo function.
162                 If you want to emphasis a parameter name then you use the following
163                 tag <VERB>x</VERB>, if you want to emphasis a part of text
164                 <EM>inclose it inside theses tags</EM> and use theses ones
165                 <BD>to have a bold font</BD> and finally <TT>for a type writer style</TT>.
166              </P>
167              <P>
168                 A second paragraph... Here is an example of a link to another page :
169                 <ALINK>man</ALINK>.
170              </P>
171          </DESCRIPTION>
172    
173         ]]></programlisting>
174     <para>
175   Here is how to write your own entry, for instance to describe some outside remarks
176   and/or notes about your wonderful function.  
177   </para>
178     <programlisting><![CDATA[
179
180          <SECTION label='Notes'>
181              <P>
182                 Here is a list of notes :
183              </P>
184              <ITEM label='first'><SP>blablabla...</SP></ITEM>
185              <ITEM label='second'><SP>toto is the french foo...</SP></ITEM>
186          </SECTION>
187    
188         ]]></programlisting>
189     <para>
190   An important entry is the <literal>EXAMPLE</literal> one which is reserved to show scilab
191   uses of your function (begin with simple ones !). Note that you must close this entry
192   with  <literal>]]&gt;&lt;/EXAMPLE&gt;</literal> and not like here with <literal>}}&gt;&lt;/EXAMPLE&gt;</literal>
193   (once again this is a bad trick to avoid some interpretation problems).</para>
194     <programlisting><![CDATA[
195
196          <EXAMPLE><![CDATA[
197              deff("y=foo(x)","y=x"); // define the foo function as the identity function
198              foo("toto")
199       }}></EXAMPLE>
200    
201         ]]></programlisting>
202     <para>
203   This last part explains how to put the links onto others related help pages 
204   (as said before the good tags are in fact <literal>&lt;LINK&gt;</literal> and 
205   <literal>&lt;/LINK&gt;</literal> and not <literal>&lt;ALINK&gt;</literal> and 
206   <literal>&lt;/ALINK&gt;</literal> ) and finally how to reveal your name if you want 
207   (use one <literal>AUTHOR_ITEM</literal> entry by author). Perhaps it is a good idea 
208   to put an email adress if you look for bug reports !</para>
209     <programlisting><![CDATA[
210
211          <SEE_ALSO>
212            <SEE_ALSO_ITEM> <ALINK>man</ALINK> </SEE_ALSO_ITEM>
213            <SEE_ALSO_ITEM> <ALINK>apropos</ALINK> </SEE_ALSO_ITEM>
214          </SEE_ALSO>
215
216          <AUTHOR>
217            <AUTHOR_ITEM>B. P.</AUTHOR_ITEM>
218          </AUTHOR>
219        </MAN>
220    
221         ]]></programlisting>
222   </refsection>
223   <refsection>
224     <title>How to create an help chapter</title>
225     <para> Create a directory and write down a set of xml files build as described
226     above. Then start Scilab and execute <literal>xmltohtml(dir)</literal>, where
227       <literal>dir</literal> is a character string giving the path of the directory
228       (see <link linkend="xmltohtml">xmltohtml</link> for more details) .</para>
229   </refsection>
230   <refsection>
231     <title>How to make Scilab know a new help chapter</title>
232     <para>This can be done by the function <link linkend="add_help_chapter">add_help_chapter</link>.</para>
233   </refsection>
234   <refsection>
235     <title>Examples</title>
236     <programlisting role="example"><![CDATA[
237     function y=foo(a,b,c),y=a+2*b+c,endfunction
238     path=help_skeleton('foo',TMPDIR)
239     scipad(path)
240   ]]></programlisting>
241   </refsection>
242   <refsection>
243     <title>See Also</title>
244     <simplelist type="inline">
245       <member>
246         <link linkend="apropos">apropos</link>
247       </member>
248       <member>
249         <link linkend="help">help</link>
250       </member>
251       <member>
252         <link linkend="help_skeleton">help_skeleton</link>
253       </member>
254     </simplelist>
255   </refsection>
256 </refentry>