0a324532e0388c2e715a67094484739b976d5007
[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  * Copyright (C) 2010 - DIGITEO - Allan CORNET
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
12  *
13  -->
14 <refentry version="5.0-subset Scilab" xml:id="man" xml:lang="en"
15           xmlns="http://docbook.org/ns/docbook"
16           xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg"
18           xmlns:ns4="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML"
20           xmlns:db="http://docbook.org/ns/docbook">
21   <info>
22     <pubdate>$LastChangedDate$</pubdate>
23   </info>
24
25   <refnamediv>
26     <refname>man</refname>
27
28     <refpurpose>on line help XML file description format</refpurpose>
29   </refnamediv>
30
31   <refsection>
32     <title>Description</title>
33
34     <para>The on line help source files are written in XML.</para>
35
36     <para>Source files (with extension .xml) can be found in the
37     <literal>&lt;SCIDIR&gt;/modules/&lt;MODULE
38     NAME&gt;/help/&lt;language&gt;/*</literal> directories. The file name is
39     usually associated to a keyword (corresponding to a function name most of
40     the cases) it describes.</para>
41   </refsection>
42
43   <refsection>
44     <title>A few words about XML</title>
45
46     <para>An XML file resembles to a hTML file but with a more rigid syntax.
47     The documentation of Scilab must be written using the strict subset of
48     DocBook 5 defined in SCI/modules/helptools/schema/scilab.rnc. DocBook 5
49     elements are fully documented in <ulink
50     url="http://docbook.org/tdg5/en/html/docbook.html">"DocBook 5.0 : The
51     Definitive Guide"</ulink></para>
52   </refsection>
53
54   <refsection>
55     <title>How to write a simple xml scilab help page:</title>
56
57     <para>If one want to write the xml file associated to a new scilab
58     function he or she may use the Scilab function <link
59     linkend="help_skeleton">help_skeleton</link> to produce the skeleton of
60     the xml file. In most cases the user will not be required to know xml
61     syntax.</para>
62   </refsection>
63
64   <refsection>
65     <title>How to write a simple xml scilab help page: an example</title>
66
67     <para>The root element of a document which conforms to the Scilab DocBook
68     5 subset must have version attribute set to "5.0-subset Scilab".</para>
69
70     <programlisting role="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
71 &lt;refentry version="5.0-subset Scilab" xml:id="foo" xml:lang="en"
72           xmlns="http://docbook.org/ns/docbook"
73           xmlns:xlink="http://www.w3.org/1999/xlink"
74           xmlns:svg="http://www.w3.org/2000/svg"
75           xmlns:ns4="http://www.w3.org/1999/xhtml"
76           xmlns:mml="http://www.w3.org/1998/Math/MathML"
77           xmlns:db="http://docbook.org/ns/docbook"&gt; </programlisting>
78
79     <refsection>
80       <title>Example:</title>
81
82       <programlisting role="example">function y = foo(a,b,c)
83   y = a + 2 * b + c;
84 endfunction
85
86 path = help_skeleton('foo', TMPDIR)
87 if (isdef('editor') | (funptr('editor')&lt;&gt;0)) then
88   editor(path);
89 end</programlisting>
90     </refsection>
91
92     <refsection>
93       <title>Generated foo.xml in TMPDIR:</title>
94     </refsection>
95
96     <programlisting role="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
97 &lt;!--
98  * Add some comments about XML file
99 --&gt;
100 &lt;refentry version="5.0-subset Scilab" xml:id="foo" xml:lang="en"
101           xmlns="http://docbook.org/ns/docbook"
102           xmlns:xlink="http://www.w3.org/1999/xlink"
103           xmlns:svg="http://www.w3.org/2000/svg"
104           xmlns:ns4="http://www.w3.org/1999/xhtml"
105           xmlns:mml="http://www.w3.org/1998/Math/MathML"
106           xmlns:db="http://docbook.org/ns/docbook"&gt;
107   &lt;info&gt;
108     &lt;pubdate&gt;$LastChangedDate: 29-11-2010 $&lt;/pubdate&gt;
109   &lt;/info&gt;
110   &lt;refnamediv&gt;
111     &lt;refname&gt;foo&lt;/refname&gt;
112     &lt;refpurpose&gt;Add short description here. &lt;/refpurpose&gt;
113   &lt;/refnamediv&gt;
114   &lt;refsynopsisdiv&gt;
115     &lt;title&gt;Calling Sequence&lt;/title&gt;
116     &lt;synopsis&gt;y = foo(a,b,c)&lt;/synopsis&gt;
117   &lt;/refsynopsisdiv&gt;
118   &lt;refsection&gt;
119     &lt;title&gt;Parameters&lt;/title&gt;
120     &lt;variablelist&gt;
121       &lt;varlistentry&gt;
122         &lt;term&gt;a&lt;/term&gt;
123         &lt;listitem&gt;
124           &lt;para&gt;
125             Add here the parameter description.
126           &lt;/para&gt;
127         &lt;/listitem&gt;
128       &lt;/varlistentry&gt;
129       &lt;varlistentry&gt;
130         &lt;term&gt;b&lt;/term&gt;
131         &lt;listitem&gt;
132           &lt;para&gt;
133             Add here the parameter description.
134           &lt;/para&gt;
135         &lt;/listitem&gt;
136       &lt;/varlistentry&gt;
137       &lt;varlistentry&gt;
138         &lt;term&gt;c&lt;/term&gt;
139         &lt;listitem&gt;
140           &lt;para&gt;
141             Add here the parameter description.
142           &lt;/para&gt;
143         &lt;/listitem&gt;
144       &lt;/varlistentry&gt;
145       &lt;varlistentry&gt;
146         &lt;term&gt;y&lt;/term&gt;
147         &lt;listitem&gt;
148           &lt;para&gt;
149             Add here the parameter description.
150           &lt;/para&gt;
151         &lt;/listitem&gt;
152       &lt;/varlistentry&gt;
153     &lt;/variablelist&gt;
154   &lt;/refsection&gt;
155   &lt;refsection&gt;
156     &lt;title&gt;Description&lt;/title&gt;
157     &lt;para&gt;
158           Add here a paragraph of the function description. 
159           Other paragraph can be added 
160     &lt;/para&gt;
161   &lt;/refsection&gt;
162   &lt;refsection&gt;
163     &lt;title&gt;Examples&lt;/title&gt;
164     &lt;programlisting role="example"&gt;&lt;![CDATA[
165         Add here scilab instructions and comments
166     ]]&gt;&lt;/programlisting&gt;
167   &lt;/refsection&gt;
168   &lt;refsection&gt;
169     &lt;title&gt;See Also&lt;/title&gt;
170     &lt;simplelist type="inline"&gt;
171       &lt;member&gt;
172         &lt;link linkend="add a reference name" &gt;add a reference&lt;/link&gt;
173       &lt;/member&gt;
174       &lt;member&gt;
175         &lt;link linkend="add a reference name"&gt;add a reference&lt;/link&gt;
176       &lt;/member&gt;
177     &lt;/simplelist&gt;
178   &lt;/refsection&gt;
179   &lt;refsection&gt;
180     &lt;title&gt;Authors&lt;/title&gt;
181     &lt;simplelist type="vert"&gt;
182       &lt;member&gt;add the author name and author reference&lt;/member&gt;
183       &lt;member&gt;add another author name and it's reference&lt;/member&gt;
184     &lt;/simplelist&gt;
185   &lt;/refsection&gt;
186   &lt;refsection&gt;
187      &lt;title&gt;Bibliography&lt;/title&gt;
188        &lt;para&gt;
189          Add here the function bibliography
190        &lt;/para&gt;
191      &lt;/refsection&gt;
192   &lt;refsection&gt;
193      &lt;title&gt;Used Functions&lt;/title&gt;
194        &lt;para&gt;
195          Add here the Scilab, C,... used code references
196        &lt;/para&gt;
197      &lt;/refsection&gt;
198 &lt;/refentry&gt;</programlisting>
199   </refsection>
200
201
202   <refsection>
203     <title>How to create a help chapter</title>
204
205     <para>Create a directory and write down a set of xml files build as
206     described above. Then start Scilab and execute <literal>xmltojar
207     </literal> (see <link linkend="xmltojar">xmltojar</link> for more details)
208     .</para>
209   </refsection>
210
211   <refsection>
212     <title>How to make Scilab know a new help chapter</title>
213
214     <para>This can be done by the function <link
215     linkend="add_help_chapter">add_help_chapter</link>.</para>
216   </refsection>
217   <refsection role="see also">
218 <title>See Also</title>
219     <simplelist type="inline">
220       <member><link linkend="apropos">apropos</link></member>
221
222       <member><link linkend="help">help</link></member>
223
224       <member><link linkend="help_skeleton">help_skeleton</link></member>
225
226       <member><link linkend="help_from_sci">help_from_sci</link></member>
227
228       <member><link linkend="xmltojar">xmltojar</link></member>
229
230       <member><link
231       linkend="add_help_chapter">add_help_chapter</link></member>
232     </simplelist>
233   </refsection>
234 </refentry>