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