b0930d9a13e8d20df0d603af270158284c546aa9
[scilab.git] / scilab / modules / helptools / macros / help_skeleton.sci
1 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
2 // Copyright (C) 2008 - INRIA
3 // Copyright (C) 2009 - DIGITEO - Allan CORNET
4 //
5 // Copyright (C) 2012 - 2016 - Scilab Enterprises
6 //
7 // This file is hereby licensed under the terms of the GNU GPL v2.0,
8 // pursuant to article 5.3.4 of the CeCILL v.2.1.
9 // This file was originally licensed under the terms of the CeCILL v2.1,
10 // and continues to be available under such terms.
11 // For more information, see the COPYING file which you should have received
12 // along with this program.
13
14 function txt = help_skeleton(funname, path, language)
15
16     [lhs,rhs] = argn(0);
17
18     if rhs > 3 | rhs < 1 then
19         error(39);
20     end
21
22     if type(funname) <> 10 then
23         error(999,msprintf(gettext("%s: Wrong type for input argument #%d: string expected.\n"),"help_skeleton",1));
24     end
25
26     if size(funname, "*") <> 1 then
27         error(999,msprintf(gettext("%s: Wrong size for input argument #%d: string expected.\n"),"help_skeleton",1));
28     end
29
30     if rhs > 1 then
31         if type(path) <> 10 then
32             error(55,2);
33         end
34     end
35
36     previouslangage = getlanguage();
37
38     if rhs == 3 then
39         if type(language) <> 10 then
40             error(55,3);
41         end
42         setlanguage(language);
43     else
44         language = getlanguage();
45     end
46
47     txt = [];
48     vars = macrovar(evstr(funname));
49     inputs = vars(1);
50     outputs = vars(2);
51     context = vars(3);
52     Call = "";
53
54     if size(outputs,"*") == 1 then
55         Call = outputs + " = "
56     elseif size(outputs,"*") > 1 then
57         Call = "["+strcat(outputs,",")+"] = ";
58     end
59
60     Call = Call + funname;
61
62     if size(inputs,"*") >= 1 then
63         Call = Call+"("+strcat(inputs,",")+")";
64     end
65
66     args = [inputs(:);outputs(:)];
67
68     // date management
69     // --------------------------------------------------------------------------------
70     w = getdate();
71     xml_date = msprintf("%02d-%02d-%04d",w(6),w(2),w(1));
72
73     //header
74     // --------------------------------------------------------------------------------
75     xmlns = "xmlns=""http://docbook.org/ns/docbook"""
76     xlink = "xmlns:xlink=""http://www.w3.org/1999/xlink"""
77     svg = "xmlns:svg=""http://www.w3.org/2000/svg"""
78     mml = " xmlns:mml=""http://www.w3.org/1998/Math/MathML"""
79     db = "xmlns:db=""http://docbook.org/ns/docbook"""
80     scins = "xmlns:scilab=""http://www.scilab.org"""
81
82     refs = strcat([xmlns xlink svg mml db scins]," ")
83
84     txt=["<?xml version=""1.0"" encoding='"UTF-8""?>"
85     "<!--"
86     _(" * Add some comments about XML file");
87     "-->"
88     "<refentry " + refs + " xml:lang="""+ language + """ xml:id=""" + funname + """>"
89     "  <refnamediv>"
90     "    <refname>"+ funname + "</refname>"
91     "    <refpurpose>" + _("Add short description here.") + "</refpurpose>"
92     "  </refnamediv>"
93     "  <refsynopsisdiv>"
94     "    <title>" + _("Syntax") + "</title>"
95     "    <synopsis>" + Call + "</synopsis>"
96     "  </refsynopsisdiv>"];
97
98     //Arguments
99     if size(args,"*") >0 then
100         txt=[txt;
101         "  <refsection>"
102         "    <title>" + _("Arguments") + "</title>"
103         "    <variablelist>"]
104         for a=args'
105             txt=[txt;
106             "      <varlistentry>"
107             "        <term>" + a + "</term>"
108             "        <listitem>"
109             "          <para>"
110             _("            Add here the input/output argument description.")
111             "          </para>"
112             "        </listitem>"
113             "      </varlistentry>"]
114         end
115         txt=[txt;
116         "    </variablelist>"
117         "  </refsection>"];
118     end
119
120     //Description
121     txt=[txt;
122     "  <refsection>"
123     "    <title>" + _("Description") + "</title>"
124     "    <para>"
125     _("          Add here a paragraph of the function description.")
126     _("          Other paragraph can be added")
127     "    </para>"
128     "    <para>With a latex expression"
129     "          <latex>"
130     "            \begin{eqnarray}"
131     "    f(x,a,r) = \frac{1}{r^{-a}\Gamma(a)} \int_0^x t^{a-1} \exp\left(-rt\right) dt"
132     "    \end{eqnarray}"
133     "    </latex>"
134     "    </para>"
135     "  </refsection>"];
136
137     // More information
138     txt=[txt;
139     "  <refsection>"
140     "    <title>" + _("More information") + "</title>"
141     "    <note><para>A note about foo</para></note>"
142     "    <caution><para>A caution about foo</para></caution>"
143     "    <warning><para>A warning about foo</para></warning>"
144     "    <important><para>An important about foo</para></important>"
145     "    <tip><para>A tip about foo</para></tip>"
146     "  </refsection>"];
147
148     //Example
149     txt=[txt;
150     "  <refsection>"
151     "    <title>" + _("Examples") + "</title>"
152     "    <programlisting role=""example""><![CDATA["
153     _("        Add here scilab instructions and comments")
154     "    ]]></programlisting>"
155     "    <scilab:image><![CDATA["
156     "// "+_("        Add here scilab instructions to generate a graphic")
157     "    ]]></scilab:image>"
158     "  </refsection>"];
159
160     //See Also
161     txt=[txt;
162     "  <refsection>"
163     "    <title>" + _("See Also") + "</title>"
164     "    <simplelist type=""inline"">"
165     "      <member>"
166     "        <link linkend=""" + _("add a reference name") + """ >" + _("add a reference") + "</link>"
167     "      </member>"
168     "      <member>"
169     "        <link linkend=""" + _("add a reference name") + """>" + _("add a reference") + "</link>"
170     "      </member>"
171     "    </simplelist>"
172     "  </refsection>"];
173
174     //Authors
175     txt=[txt;
176     "  <refsection>"
177     "    <title>" + _("Authors") + "</title>"
178     "    <simplelist type=""vert"">"
179     "      <member>" + _("add the author name and author reference") + "</member>"
180     "      <member>" + _("add another author name and his/her reference") + "</member>"
181     "    </simplelist>"
182     "  </refsection>"];
183
184     //Bibliography
185     txt = [txt;
186     "  <refsection>"
187     "     <title>" + _("Bibliography") + "</title>"
188     "       <para>"
189     _("         Add here the function bibliography")
190     "       </para>"
191     "     </refsection>"];
192
193     // History
194     txt = [txt;
195     "    <refsection>"
196     "       <title>" + _("History") + "</title>"
197     "      <revhistory>"
198     "        <revision>"
199     "          <revnumber>X.Y</revnumber>"
200     "          <revdescription>Function foo added</revdescription>"
201     "        </revision>"
202     "      </revhistory>"
203     "    </refsection>"];
204
205     //Used functions
206     txt=[txt;
207     "  <refsection>"
208     "     <title>" + _("Used Functions") + "</title>"
209     "       <para>"
210     _("         Add here the Scilab, C,... used code references")
211     "       </para>"
212     "     </refsection>"];
213
214     //footer
215     txt=[txt;
216     "</refentry>"];
217
218     setlanguage(previouslangage);
219
220     if rhs >= 2 then
221         mputl(txt, pathconvert(path,%t,%f) + funname + ".xml");
222         txt = pathconvert(path,%t,%f) + funname + ".xml";
223     end
224
225 endfunction