add CDATA + role in the helptools module
[scilab.git] / scilab / modules / helptools / help / en_US / percenthelps.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="helps">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>%helps</refname>
19     <refpurpose> Variable defining the path of help directories</refpurpose>
20   </refnamediv>
21   <refsection>
22     <title>Description</title>
23     <para>
24     The global variable <literal>%helps</literal> is an N x 2 matrix of strings. 
25     The kth row of <literal>%helps</literal>, <literal>%helps(k,:)</literal> represents
26     the kth chapter of the manual and is made of two strings:</para>
27     <para><literal>%helps(k,1)</literal> is the absolute pathname for a help directory.</para>
28     <para><literal>%helps(k,2)</literal> is a title for this help directory.
29     For instance, for k=2, we have the graphics chapter 
30     <literal>%helps(2,:)</literal>.</para>
31     <para>
32     The variable <literal>%helps</literal> is defined in the Scilab startup
33     file <literal>SCI+"/scilab.start"</literal>.</para>
34     <para>
35     To add a new help directory, the user should add a row to
36     the variable <literal>%helps</literal>. (One row for each directory).</para>
37     <para>
38     For instance, <literal>%helps=[%helps; "Path-Of-My-Help-Dir","My-Title"];</literal>
39     enables the Scilab help browser to look for help manual items
40     in the directory with pathname "Path-Of-My-Help-Dir".</para>
41     <para>
42     "My-Title" is then the title of a new help chapter.</para>
43     <para>
44     A valid help directory must contain:</para>
45     <para>
46     1- A set of <literal>.html</literal> files (e.g. <literal>item1.html, item2.html</literal> etc).
47     The <literal>.html</literal> files are usually built from XML files.</para>
48     <para>
49     2- A <literal>whatis.html</literal> file, which must have a special format. Each row
50     of the <literal>whatis</literal> must be as follows:</para>
51     <programlisting role = ""><![CDATA[ 
52 <BR><A HREF="item.html">item</A> - quick description
53  ]]></programlisting>
54     <para><literal>item</literal> is the item of the help, i.e. the command <literal>help item</literal>
55     displays the contents of the file <literal>item.html</literal>.</para>
56     <para>
57     The command <literal>apropos keyword</literal> returns the row(s) of all
58     the <literal>whatis.html</literal> file(s) in which the keyword appears.</para>
59     <para>
60     On Linux platforms Scilab provides a Makefile for transforming
61     <literal>.xml</literal> pages into <literal>.html</literal> pages (see SCIDIR/examples/man-examples).</para>
62   </refsection>
63   <refsection>
64     <title>See Also</title>
65     <simplelist type="inline">
66       <member>
67         <link linkend="apropos">apropos</link>
68       </member>
69       <member>
70         <link linkend="help">help</link>
71       </member>
72       <member>
73         <link linkend="man">man</link>
74       </member>
75     </simplelist>
76   </refsection>
77 </refentry>