Remove all the authors from the documentation. This has been done for the following...
[scilab.git] / scilab / modules / helptools / help / en_US / help_from_sci.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  *
4  * This help file was generated from help_from_sci.sci using help_from_sci().
5  *
6  -->
7 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="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="help_from_sci" xml:lang="en">
8   <info>
9     <pubdate>$LastChangedDate: 05-Aug-2011 $</pubdate>
10   </info>
11   <refnamediv>
12     <refname>help_from_sci</refname>
13     <refpurpose>Generate help files and demo files from the head comments section of a .sci source file.</refpurpose>
14   </refnamediv>
15   <refsynopsisdiv>
16     <title>Calling Sequence</title>
17     <synopsis>
18       help_from_sci() // generate an empty function template
19       helptxt = help_from_sci() // generate an empty function template
20       help_from_sci(funname,helpdir) // generate helpdir/funname.xml from funname.sci.
21       help_from_sci(dirname,helpdir) // process dirname/*.sci and create helpdir/*.xml help files.
22       help_from_sci(dirname,helpdir,demodir) // as above but also creating demodir/*.dem.sce demo files.
23       [helptxt,demotxt]=help_from_sci(funname) // return funname.xml and funname.dem.sce code as two text matrixes.
24     </synopsis>
25   </refsynopsisdiv>
26   <refsection>
27     <title>Parameters</title>
28     <variablelist>
29       <varlistentry>
30         <term>funname:</term>
31         <listitem>
32           <para> the name of a single .sci source file to be processed.</para>
33         </listitem>
34       </varlistentry>
35       <varlistentry>
36         <term>dirname:</term>
37         <listitem>
38           <para> directory name where all .sci files will be processed.</para>
39         </listitem>
40       </varlistentry>
41       <varlistentry>
42         <term>helpdir:</term>
43         <listitem>
44           <para> optional path where the .xml help file will be created.</para>
45         </listitem>
46       </varlistentry>
47       <varlistentry>
48         <term>demodir:</term>
49         <listitem>
50           <para> optional path where .dem.sce demo files will be created based on code from the Examples section.</para>
51         </listitem>
52       </varlistentry>
53       <varlistentry>
54         <term>helptxt:</term>
55         <listitem>
56           <para> returns the XML help code if helpdir is empty, or the path to the .xml file.</para>
57         </listitem>
58       </varlistentry>
59       <varlistentry>
60         <term>demotxt:</term>
61         <listitem>
62           <para> returns the demo code if demodir is empty, or the path to the .dem.sce file.</para>
63         </listitem>
64       </varlistentry>
65     </variablelist>
66   </refsection>
67   <refsection>
68     <title>Description</title>
69     <para>
70       The help_from_sci function generates .xml help files based on the head comments section
71       of .sci source files. Optionally .dem.sce demo files can be generated based on
72       code from the Examples section in the head comments section of .sci files.
73     </para>
74     <para>
75       In order for help_from_sci to format the .xml file properly the
76       head comments section should comply with some simple formatting rules.
77     </para>
78     <para>
79       The first comment line following the function definition should contain a short description
80       of the function.
81     </para>
82     <para>
83       The remaining comments are formatted according to the following (optional) headlines:
84       "Calling Sequence", "Parameters", "Description", "Examples", "See also", "Used functions",
85       "Authors" and "Bibliography".
86     </para>
87     <para>
88       The following guidelines should be used when writing the source code comments:
89       <itemizedlist>
90         <listitem>
91           <para>
92             <literal>Calling Sequence</literal> - one example pr. line.
93           </para>
94         </listitem>
95         <listitem>
96           <para>
97             <literal>Parameters</literal> - separate parameter name and
98             description by a ":". Keep the description of each parameter on the same line.
99           </para>
100         </listitem>
101         <listitem>
102           <para>
103             <literal>Description</literal> - formatting of the text can be done
104             using XML commands. Compare the output of head_comments("help_from_sci") with help("help_from_sci")
105             to get some hints.
106             Adding an empty comment line in the Description section is interpreted as the
107             start of a new paragraph.
108           </para>
109         </listitem>
110         <listitem>
111           <para>
112             <literal>See also</literal> - list one function name pr line.
113           </para>
114         </listitem>
115         <listitem>
116           <para>
117             <literal>Authors</literal> - write one author on each line following
118             the Authors headline. Use ";" to separate the authors name
119             from any add additional information.
120           </para>
121         </listitem>
122         <listitem>
123           <para>
124             <literal>Bibliography</literal> - write one reference pr line
125             following the References headline.
126           </para>
127         </listitem>
128       </itemizedlist>
129     </para>
130     <para>
131     </para>
132   </refsection>
133   <refsection>
134     <title>Examples</title>
135     <programlisting role="example"><![CDATA[
136 help_from_sci()   // Open an empty source code template in the scinotes editor.
137 // Save this template as test_fun.sci in the current directory before running
138 // the next example commands.
139
140 help_from_sci("test_fun")        // return the xml skeleton as a text string
141
142 help_from_sci("test_fun",".")    // create the xml help file in the current directory.
143
144 // create both a xml help file and a demo file in the current directory.
145 help_from_sci("test_fun",".",".")
146
147 // From a toolbox root directory a typical calling sequence would be:
148 // help_from_sci("macros","help\en_US","demos")
149 // This command would process all .sci files in the macros directory
150 // and use the head comments section to update all .xml help files in the
151 // help\en_US directory an rebuild the .dem.sce files in the demos\ directory.
152
153    ]]></programlisting>
154   </refsection>
155   <refsection>
156     <title>See also</title>
157     <simplelist type="inline">
158       <member>
159         <link linkend="help">help</link>
160       </member>
161       <member>
162         <link linkend="help_skeleton">help_skeleton</link>
163       </member>
164       <member>
165         <link linkend="head_comments">head_comments</link>
166       </member>
167     </simplelist>
168   </refsection>
169 </refentry>