* Bug 6911 fixed: help_from_sci dit not support ω in heading comments
[scilab.git] / scilab / modules / helptools / help / pt_BR / 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"
8           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns3="http://www.w3.org/1999/xhtml"
9           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
10           xmlns:scilab="http://www.scilab.org" xml:id="help_from_sci" xml:lang="pt">
11     <refnamediv>
12         <refname>help_from_sci</refname>
13         <refpurpose>Geração de arquivos de ajuda e de arquivos de demonstração a
14             partir da seção de comentários de cabeçalho de um arquivo-fonte
15             .sci
16         </refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Seqüência de Chamamento</title>
20         <synopsis>
21             help_from_sci() // gera um modelo de função vazio
22             help_from_sci(funname,helpdir) // gera helpdir/funname.xml a partir de funname.sci
23             help_from_sci(dirname,helpdir) // processa dirname/*.sci e cria helpdir/*.xml.
24             help_from_sci(dirname,helpdir,helpdir) // como acima, mas também cria o arquivo de demonstração helpdir/*.dem.sce.
25             [helptxt,demotxt]=help_from_sci(funname) // retorna funname.xml e funname.dem.sce como duas matrizes de texto.
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Parâmetros</title>
30         <variablelist>
31             <varlistentry>
32                 <term>funname:</term>
33                 <listitem>
34                     <para>o nome de um único arquivo .sci a ser processado</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>dirname:</term>
39                 <listitem>
40                     <para>nome do diretório onde todos os arquivos .sci serão
41                         processados
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>helpdir:</term>
47                 <listitem>
48                     <para>endereço opcional onde o arquivo de ajuda .xml será
49                         criado
50                     </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>demodir:</term>
55                 <listitem>
56                     <para>endereço opcional onde os arquivos de demonstração .dem.sce
57                         serão criados baseados nos códigos da seção Examples
58                     </para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>helptxt:</term>
63                 <listitem>
64                     <para>retorna o código da ajuda XML se helpdir for vazio, ou o
65                         endereço para o novo arquivo .xml
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>demotxt:</term>
71                 <listitem>
72                     <para>retorna o código de demonstração se demodir for vazio, ou o
73                         endereço para o novo arquivo .dem.sc
74                     </para>
75                 </listitem>
76             </varlistentry>
77         </variablelist>
78     </refsection>
79     <refsection>
80         <title>Descrição</title>
81         <para>help_from_sci é uma versão revisada da função help_skeleton. Seu
82             objetivo é gerar arquivos de ajuda .xml baseados na seção de comentários
83             de cabeçalho dos arquivos-fontes .sci. Opcionalmente, os arquivos de
84             demonstração .dem.sce podem ser gerados baseados nos códigos da seção
85             Examples na seção de cometários de cabeçalho dos arquivos .sci.
86         </para>
87         <para>Para que help_from_sci formate o arquivo .xml propriamente, os a
88             seção de comentários de cabeçalho deve concordar com algumas regras
89             simples de formatação.
90         </para>
91         <para>A primeira linha de comentário seguinte à definição de função deve
92             conter uma descrição breve da função.
93         </para>
94         <para>Os comentários restantes são formatados de acordo com os seguintes
95             cabeçalhos (opcionais): "Syntax", "Parameters", "Description",
96             "Examples", "See also", "Used functions", "Authors" e
97             "Bibliography".
98         </para>
99         <para>As seguintes diretrizes devem ser seguidas ao se escrever os
100             comentários de código fonte:
101         </para>
102         <itemizedlist>
103             <listitem>
104                 <para>
105                     <literal>Syntax</literal>
106                     - um exemplo por linha.
107                 </para>
108             </listitem>
109             <listitem>
110                 <para>
111                     <literal>Parameters</literal>
112                     - separe o nome do parâmetro e a descrição por um ":". Mantenha a descrição de
113                       cada parâmetro na mesma linha.
114                 </para>
115             </listitem>
116             <listitem>
117                 <para>
118                     <literal>Description</literal>
119                     - a formatação do texto pode ser feita utilizando comandos XML. Adicionar uma
120                       linha de comentário vazia na seção Description é interpretado como começo de
121                       um novo parágrafo.
122                 </para>
123             </listitem>
124             <listitem>
125                 <para>
126                     <literal>See also</literal>
127                     - liste um nome de função por linha.
128                 </para>
129             </listitem>
130             <listitem>
131                 <para>
132                     <literal>Authors</literal>
133                     - escreva um autor em cada linha após o cabeçalho Authors. Use ";" para separar
134                       os autores de qualquer informação adicional.
135                 </para>
136             </listitem>
137             <listitem>
138                 <para>
139                     <literal>Bibliography</literal>
140                     - escreva uma referência por linha seguindo o cabeçalho References.
141                 </para>
142             </listitem>
143         </itemizedlist>
144         <note>
145           The "&amp;" character as well as numerical HTML entities like "&amp;#123;" are supported
146           in the contents. Literal HTML entities like "&amp;acute;" are not accepted. Please use
147           directly the UTF-8 character like "é" instead.
148         </note>
149         <para/>
150     </refsection>
151     <refsection>
152         <title>Exemplos</title>
153         <programlisting role="example"><![CDATA[
154 help_from_sci()   // abrindo um modelo de código-fonte vazio no editor.
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     <refsection role="see also">
173         <title>Ver Também</title>
174         <simplelist type="inline">
175             <member>
176                 <link linkend="help">help</link>
177             </member>
178             <member>
179                 <link linkend="help_skeleton">help_skeleton</link>
180             </member>
181             <member>
182                 <link linkend="xmltohtml">xmltohtml</link>
183             </member>
184         </simplelist>
185     </refsection>
186     <refsection role="history">
187         <title>Histórico</title>
188         <revhistory>
189             <revision>
190                 <revnumber>6.0.1</revnumber>
191                 <revdescription>
192                   Numerical HTML entities like <literal>&amp;#969;</literal> are now accepted in
193                   heading comments.
194                 </revdescription>
195             </revision>
196         </revhistory>
197     </refsection>
198 </refentry>