add CDATA + role in the helptools module
[scilab.git] / scilab / modules / helptools / help / pt_BR / help_from_sci.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!--
3  * 
4  * This help file was generated from help_from_sci.sci using help_from_sci().
5  * 
6  -->
7 <refentry version="5.0-subset Scilab" xml:id="help_from_sci" xml:lang="en"
8           xmlns="http://docbook.org/ns/docbook"
9           xmlns:xlink="http://www.w3.org/1999/xlink"
10           xmlns:svg="http://www.w3.org/2000/svg"
11           xmlns:ns3="http://www.w3.org/1999/xhtml"
12           xmlns:mml="http://www.w3.org/1998/Math/MathML"
13           xmlns:db="http://docbook.org/ns/docbook">
14   <info>
15     <pubdate>$LastChangedDate: 19-Oct-2008 $</pubdate>
16   </info>
17
18   <refnamediv>
19     <refname>help_from_sci</refname>
20
21     <refpurpose>Geração de arquivos de ajuda e de arquivos de demonstração a
22     partir da seção de comentários de cabeçalho de um arquivo-fonte
23     .sci</refpurpose>
24   </refnamediv>
25
26   <refsynopsisdiv>
27     <title>Seqüência de Chamamento</title>
28
29     <synopsis>
30       help_from_sci() // gera um modelo de função vazio
31       help_from_sci(funname,helpdir) // gera helpdir/funname.xml a partir de funname.sci
32       help_from_sci(dirname,helpdir) // processa dirname/*.sci e cria helpdir/*.xml.
33       help_from_sci(dirname,helpdir,helpdir) // como acima, mas também cria o arquivo de demonstração helpdir/*.dem.sce.
34       [helptxt,demotxt]=help_from_sci(funname) // retorna funname.xml e funname.dem.sce como duas matrizes de texto.
35     </synopsis>
36   </refsynopsisdiv>
37
38   <refsection>
39     <title>Parâmetros</title>
40
41     <variablelist>
42       <varlistentry>
43         <term>funname:</term>
44
45         <listitem>
46           <para>o nome de um único arquivo .sci a ser processado</para>
47         </listitem>
48       </varlistentry>
49
50       <varlistentry>
51         <term>dirname:</term>
52
53         <listitem>
54           <para>nome do diretório onde todos os arquivos .sci serão
55           processados</para>
56         </listitem>
57       </varlistentry>
58
59       <varlistentry>
60         <term>helpdir:</term>
61
62         <listitem>
63           <para>endereço opcional onde o arquivo de ajuda .xml será
64           criado</para>
65         </listitem>
66       </varlistentry>
67
68       <varlistentry>
69         <term>demodir:</term>
70
71         <listitem>
72           <para>endereço opcional onde os arquivos de demonstração .dem.sce
73           serão criados baseados nos códigos da seção Examples</para>
74         </listitem>
75       </varlistentry>
76
77       <varlistentry>
78         <term>helptxt:</term>
79
80         <listitem>
81           <para>retorna o código da ajuda XML se helpdir for vazio, ou o
82           endereço para o novo arquivo .xml</para>
83         </listitem>
84       </varlistentry>
85
86       <varlistentry>
87         <term>demotxt:</term>
88
89         <listitem>
90           <para>retorna o código de demonstração se demodir for vazio, ou o
91           endereço para o novo arquivo .dem.sc</para>
92         </listitem>
93       </varlistentry>
94     </variablelist>
95   </refsection>
96
97   <refsection>
98     <title>Descrição</title>
99
100     <para>help_from_sci é uma versão revisada da função help_skeleton. Seu
101     objetivo é gerar arquivos de ajuda .xml baseados na seção de comentários
102     de cabeçalho dos arquivos-fontes .sci. Opcionalmente, os arquivos de
103     demonstração .dem.sce podem ser gerados baseados nos códigos da seção
104     Examples na seção de cometários de cabeçalho dos arquivos .sci.</para>
105
106     <para>Para que help_from_sci formate o arquivo .xml propriamente, os a
107     seção de comentários de cabeçalho deve concordar com algumas regras
108     simples de formatação.</para>
109
110     <para>A primeira linha de comentário seguinte à definição de função deve
111     conter uma descrição breve da função.</para>
112
113     <para>Os comentários restantes são formatados de acordo com os seguintes
114     cabeçalhos (opcionais): "Calling Sequence", "Parameters", "Description",
115     "Examples", "See also", "Used functions", "Authors" e
116     "Bibliography".</para>
117
118     <para>As seguintes diretrizes devem ser seguidas ao se escrever os
119     comentários de código fonte:</para>
120       <itemizedlist>
121         <listitem><para>       
122           <literal>Calling Sequence</literal>
123            - um exemplo por linha. 
124         </para></listitem>
125         <listitem><para>
126           <literal>Parameters</literal>
127            - separe o nome do parâmetro e a descrição por um ":". Mantenha a descrição de cada parâmetro na mesma linha. 
128         </para></listitem>
129         <listitem><para>
130           <literal>Description</literal>
131            - a formatação do texto pode ser feita utilizando comandos XML. Adicionar uma linha de comentário vazia na seção Description é interpretado como começo de um novo parágrafo. 
132           </para></listitem>
133         <listitem><para>
134           <literal>See also</literal>
135            - liste um nome de função por linha.
136           </para></listitem>
137         <listitem><para>
138           <literal>Authors</literal>
139            - escreva um autor em cada linha após o cabeçalho Authors. Use ";" para separar os autores de qualquer informação adicional. 
140           </para></listitem>
141         <listitem><para>
142           <literal>Bibliography</literal>
143            - escreva uma referência por linha seguindo o cabeçalho References. 
144           </para></listitem>
145       </itemizedlist>
146
147     <para></para>
148   </refsection>
149
150   <refsection>
151     <title>Exemplos</title>
152
153     <programlisting role="example"><![CDATA[ 
154 help_from_sci()   // abrindo um modelo de código-fonte vazio no editor Scipad.
155 // salve este modelo como test_fun.sci no diretório corrente antes de executar
156 // os próximos comandos do exemplo
157
158 help_from_sci('test_fun')        // retornando o esqueleto xml como um string de texto.
159
160 help_from_sci('test_fun','.')    // criando o arquivo de ajuda xml no diretório corrente.
161
162 // criando ambos os arquivos de ajuda e demonstração no diretório corrente.
163 help_from_sci('test_fun','.','.')
164
165 // de um diretório raiz de um toolbox, uma seqüência de chamamento típica seria:
166 // help_from_sci('macros','help\pt_BR','demos')
167 // este comando processaria todos os arquivos .sci no diretório de macros
168 // e utilizaria a seção de comentários de cabeçalho para atualizar as ajudas .xml no
169 // diretório help\en_US e reconstruiria os arquivos .dem.sce no diretório demos\.
170  ]]></programlisting>
171   </refsection>
172
173   <refsection>
174     <title>Ver Também</title>
175
176     <simplelist type="inline">
177       <member><link linkend="help">help</link></member>
178
179       <member><link linkend="help_skeleton">help_skeleton</link></member>
180
181       <member><link linkend="xmltohtml">xmltohtml</link></member>
182     </simplelist>
183   </refsection>
184
185   <refsection>
186     <title>Autor</title>
187
188     <variablelist>
189       <varlistentry>
190         <term>T. Pettersen</term>
191
192         <listitem>
193           <para>torbjorn.pettersen@broadpark.no</para>
194         </listitem>
195       </varlistentry>
196     </variablelist>
197   </refsection>
198 </refentry>