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