add CDATA + role in the helptools module
[scilab.git] / scilab / modules / helptools / help / pt_BR / man.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
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 version="5.0-subset Scilab" xml:id="man" xml:lang="en"
14           xmlns="http://docbook.org/ns/docbook"
15           xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg"
17           xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
19           xmlns:db="http://docbook.org/ns/docbook">
20   <info>
21     <pubdate>$LastChangedDate$</pubdate>
22   </info>
23
24   <refnamediv>
25     <refname>man</refname>
26
27     <refpurpose>Descrição do formato do arquivo de ajuda XML</refpurpose>
28   </refnamediv>
29
30   <refsection>
31     <title>Descrição</title>
32
33     <para>Os arquivos-fontes da ajuda Scilab são escritos em formato
34     XML</para>
35
36     <para>Arquivos-fontes (com extensão .xml) podem ser encontrados nos
37     diretórios <literal>&lt;SCIDIR&gt;/man/&lt;language&gt;/*</literal>. O
38     nome do arquivo é geralmente associado à palavra-chave (correspondente a
39     um nome de função na maioria dos casos) que descreve .</para>
40   </refsection>
41
42   <refsection>
43     <title>Breves palavras sobre XML</title>
44
45     <para>Um arquivo XML lembra um arquivo HTML, mas possui uma sintaxe tanto
46     mais rígida quanto mais livre. Livre porque você pode construir os seus
47     próprios tags (marcação): o conjunto de tags, junto com suas regras, deve
48     ser descrito em algum lugar, geralmente em outro arquivo
49     (<literal>&lt;SCIDIR&gt;/man/manrev.dtd</literal> para o Scilab), e rígida
50     porque, uma vez que os tags e regras são definidas (as quais são chamadas
51     Definição de Tipo de Documento (Document Type Definition): DTD) , você
52     deve respeitá-las (em particular, para todos os tags
53     <literal>&lt;MY_TAG&gt;</literal> abertos, deve corresponder um tag
54     fechado <literal>&lt;/MY_TAG&gt;</literal>).</para>
55
56     <para>O DTD manrev.dtd é escrito em SGML e precisa a exata sintaxe
57     requerida por uma página de ajuda XML do Scilab. Então se você conhece
58     esta linguagem, você pode ler este arquivo. O seguinte exemplo anotado
59     (veja a próxima seção) mostra algumas possibilidades oferecidas por este
60     DTD e pode ser suficiente para escrever páginas de ajuda simples.</para>
61
62     <para>Uma vez que a página XML é escrita e está em conformidade com o DTD,
63     ela pode ser transformada em um HTML para ser lida por algum navegador de
64     internet, ou pelo navegador tcltk do Scilab (ver a seção escolha do
65     navegador nesta página). A tradução XML -&gt; HTML é controlada por um
66     conjunto de regras escritas no arquivo (XML)
67     <literal>&lt;SCIDIR&gt;/man/language/html.xsl</literal>. Estas regras
68     estão correntemente mais ou menos restritas para se adequarem aos recursos
69     do navegador tcltk do Scilab (que pode exibir corretamente apenas HTML
70     básico): Se você utilizar um navegador de HTML e quiser melhorar a
71     aparência, terá que modificar este arquivo.</para>
72   </refsection>
73
74   <refsection>
75     <title>Como escrever uma página de ajuda XML do Scilab simples: a maneira
76     lazzy</title>
77
78     <para>Caso se deseje escrever um arquivo XML associado a uma nova função
79     Scilab, pode-se utilizar a função <link
80     linkend="help_skeleton">help_skeleton</link> para produzir o esqueleto do
81     arquivo XML. Na maior parte dos casos, o usuário não precisará saber a
82     sintaxe XML.</para>
83   </refsection>
84
85   <refsection>
86     <title>Como escrever uma página de ajuda XML do Scilab simples: um
87     exemplo</title>
88
89     <para>Aqui está um exemplo simples de uma página de ajuda XML que descreve
90     uma função do Scilab hipotética chamada "foo". No seguinte, o arquivo XML
91     é exibido em uma <literal>fonte de máquina-de-escrever</literal> e
92     recortado em várias partes, cada parte precedida por algumas explicações
93     associadas. O arquivo XML inteiro <literal>foo.xml</literal> está no
94     diretório <literal>&lt;SCIDIR&gt;/man/eng/utility</literal> e o resultado
95     pode ser exibido clicando-se em <link linkend="foo">foo</link> (você pode
96     encontrar outros exemplos no diretório
97     <literal>&lt;SCIDIR&gt;/examples/man-examples-xml</literal>). <emphasis
98     role="bold">Finalmente</emphasis> note que alguns pares de tags
99     <literal>&lt;TAG&gt;</literal>, <literal>&lt;/TAG&gt;</literal> foram
100     renomeados aqui <literal>&lt;ATAG&gt;</literal>,
101     <literal>&lt;/ATAG&gt;</literal>. Isto porque alguns scripts do Scilab que
102     realizam trabalhos sobre ou a partir dos arquivos XML não verificam se um
103     tag está dentro de uma entrada <literal>VERBATIM</literal>.</para>
104
105     <para>As primeiras três linhas do arquivo são mandatórias, a segunda
106     precisa o endereço para o arquivo DTD e a terceira, formada pelo tag
107     <literal>&lt;MAN&gt;</literal>, inicia a descrição hierárquica (o arquivo
108     deve terminar com o tag <literal>&lt;/MAN&gt;</literal>). As quatro
109     entradas seguintes : <literal>LANGUAGE</literal>,
110     <literal>TITLE</literal>, <literal>TYPE</literal> e
111     <literal>DATE</literal>, também são mandatórias (nesta ordem), o texto
112     correspondente a <literal>&lt;TYPE&gt;</literal> sendo geralmente 'função
113     do Scilab' (na maior parte dos casos), mas pode ser simplesmente
114     'palavra-chave do Scilab' ou 'tipo de dados do Scilab', ..., dependendo do
115     que explica a página de ajuda.</para>
116
117     <programlisting role = ""><![CDATA[ 
118 <!DOCTYPE MAN SYSTEM "<SCIDIR>/man/manrev.dtd">
119 <MAN>
120    <LANGUAGE>eng</LANGUAGE>
121    <TITLE>foo</TITLE>
122    <TYPE>função do Scilab</TYPE>
123    <DATE>$LastChangedDate$</DATE>
124  ]]></programlisting>
125
126     <para>A primeira destas duas entradas seguintes
127     (<literal>SHORT_DESCRIPTION</literal>) é mandatória e importante desde que
128     as palavras do texto da descrição curta (short description), são
129     utilizadas pelo comando <link linkend="apropos">apropos</link> para buscar
130     páginas de ajuda a partir de uma palavra-chave: a descrição curta é
131     utilizada para construir o arquivo <literal>whatis.html</literal>
132     correspondente ao seu toolbox e o comando <literal>apropos
133     keyword</literal> faz uma pesquisa em todos os arquivos whatis e propõe os
134     links para cada página onde a palavra <literal>keyword</literal> se
135     encontra em sua descrição curta (na verdade, os tags reais associados são
136     <literal>&lt;SHORT_DESCRIPTION&gt;</literal> e
137     <literal>&lt;/SHORT_DESCRIPTION&gt;</literal> e não
138     <literal>&lt;ASHORT_DESCRIPTION&gt;</literal> e
139     <literal>&lt;/ASHORT_DESCRIPTION&gt;</literal>). A próxima entrada
140     (<literal>CALLING_SEQUENCE</literal>) deve ser utilizada ao se descrever
141     uma função (mas não é estritamente mandatória). Se a sua função possui
142     várias seqüências de chamamento, utilize várias entradas
143     <literal>CALLING_SEQUENCE_ITEM</literal>.</para>
144
145     <programlisting role = ""><![CDATA[ 
146 <ASHORT_DESCRIPTION name="foo">descrição curta de foo</ASHORT_DESCRIPTION>
147 <CALLING_SEQUENCE>
148     <CALLING_SEQUENCE_ITEM>[y] = foo(x)</CALLING_SEQUENCE_ITEM>
149     </CALLING_SEQUENCE>
150  ]]></programlisting>
151
152     <para>A entrada seguinte (<literal>PARAM</literal>) não é estritamente
153     mandatória, mas é a boa para descrever cada parâmetro (de entrada e saída)
154     no caso de uma função.</para>
155
156     <programlisting role = ""><![CDATA[ 
157 <PARAM>
158    <PARAM_INDENT>
159       <PARAM_ITEM>
160          <PARAM_NAME>x</PARAM_NAME>
161          <PARAM_DESCRIPTION>
162             <SP>: o que pode ser x</SP>
163          </PARAM_DESCRIPTION> 
164       </PARAM_ITEM>
165       <PARAM_ITEM>
166          <PARAM_NAME>y</PARAM_NAME>
167          <PARAM_DESCRIPTION>
168             <SP>: o que pode ser y</SP>
169          </PARAM_DESCRIPTION> 
170       </PARAM_ITEM>
171    </PARAM_INDENT>
172 </PARAM>
173  ]]></programlisting>
174
175     <para>A entrada <literal>DESCRIPTION</literal> é talvez a mais
176     significativa (mas não é estritamente mandatória) e pode ser mais
177     sofisticada que neste exemplo (por exemplo, você pode ter sub-entradas
178     <literal>DESCRIPTION_ITEM</literal>). Aqui, você vê como escrever vários
179     parágrafos (cada um encerrado pelos tags <literal>&lt;P&gt;</literal> e
180     <literal>&lt;/P&gt;</literal>), como enfatizar uma variável, ou um nome de
181     função (encerrando-os por tags <literal>&lt;VERB&gt;</literal> e
182     <literal>&lt;/VERB&gt;</literal>), como enfatizar uma parte o texto
183     (<literal>&lt;EM&gt;</literal> ou <literal>&lt;BD&gt;</literal> e
184     <literal>&lt;TT&gt;</literal> para colocar em fonte de máquina de
185     escrever)), e, finalmente, como colocar um link para outra página de ajuda
186     (na verdade, os tags associados são <literal>&lt;LINK&gt;</literal> e
187     <literal>&lt;/LINK&gt;</literal> e não <literal>&lt;ALINK&gt;</literal> e
188     <literal>&lt;/ALINK&gt;</literal>).</para>
189
190     <programlisting role = ""><![CDATA[ 
191 <DESCRIPTION>
192     <P>
193        Um primeiro parágrafo explica o que a função foo computa.
194        Se você deseja enfatizar um nome de parâmetro, você pode utilizar o segunte
195        tag <VERB>x</VERB>, se você desejar enfatizar parte do texto
196        <EM>encerre-a nestes tags</EM> e use estes
197        <BD>para uma fonte em negrito</BD> e finalmente <TT>para um estilo em máquina de escrever</TT>.
198     </P>
199     <P>
200        Um segundo parágrafo... Aqui vai um exemplo de um link para outra página :
201        <ALINK>man</ALINK>.
202     </P>
203 </DESCRIPTION>
204  ]]></programlisting>
205
206     <para>Aqui está como escrever a sua própria entrada, por exemplo, para
207     escrever observações e/ou notas sobre a sua maravilhosa função.</para>
208
209     <programlisting role = ""><![CDATA[ 
210 <SECTION label='Notes'>
211     <P>
212        Aqui está uma lista de notas :
213     </P>
214     <ITEM label='first'><SP>blablabla...</SP></ITEM>
215     <ITEM label='second'><SP>toto é o francês de foo...</SP></ITEM>
216 </SECTION>
217  ]]></programlisting>
218
219     <para>Uma entrada importante é <literal>EXAMPLE</literal> que é reservada
220     para mostrar usos no Scilab da sua função (comece com exemplos simples!).
221     Note que você deve fechar esta entrada com
222     <literal>]]&gt;&lt;/EXAMPLE&gt;</literal> , e não como aqui com
223     <literal>}}&gt;&lt;/EXAMPLE&gt;</literal> (mais uma vez, este é um truque
224     ruim para evitar problemas de interpretação).</para>
225
226     <programlisting role = ""><![CDATA[ 
227 <EXAMPLE><![CDATA[
228     deff("y=foo(x)","y=x"); // definindo a função foo como a função identidade
229     foo("toto")
230 }}></EXAMPLE>
231  ]]></programlisting>
232
233     <para>Esta última parte explica como colocar links para outras páginas de
234     ajuda relacionadas (como já foi dito antes, os bons tags são
235     <literal>&lt;LINK&gt;</literal> e <literal>&lt;/LINK&gt;</literal> e não
236     <literal>&lt;ALINK&gt;</literal> e <literal>&lt;/ALINK&gt;</literal> ) e
237     finalmente como revelar o seu nome, se você quiser (utilize uma entrada
238     <literal>AUTHOR_ITEM</literal> por autor). Talvez seja uma boa idéia
239     colocar um endereço de email, se você procura por relatos de bugs !</para>
240
241     <programlisting role = ""><![CDATA[ 
242 <SEE_ALSO>
243   <SEE_ALSO_ITEM> <ALINK>man</ALINK> </SEE_ALSO_ITEM>
244   <SEE_ALSO_ITEM> <ALINK>apropos</ALINK> </SEE_ALSO_ITEM>
245 </SEE_ALSO>
246  <AUTHOR>
247   <AUTHOR_ITEM>B. P.</AUTHOR_ITEM>
248 </AUTHOR>
249 </MAN>
250  ]]></programlisting>
251   </refsection>
252
253   <refsection>
254     <title>Como criar um capítulo de ajuda</title>
255
256     <para>Crie um diretório e escreva um conjunto de arquivos XML construídos
257     como descrito acima. Então, inicie o Scilab e execute
258     <literal>xmltohtml(dir)</literal>, onde é um <literal>dir</literal> string
259     fornecendo o endereço do diretório (ver <link
260     linkend="xmltohtml">xmltohtml</link> para mais detalhes) .</para>
261   </refsection>
262
263   <refsection>
264     <title>Como fazer o Scilab reconhecer um novo capítulo de ajuda</title>
265
266     <para>Isto pode ser feito através da função <link
267     linkend="add_help_chapter">add_help_chapter</link>.</para>
268   </refsection>
269
270   <refsection>
271     <title>Exemplos</title>
272
273     <programlisting role="example">
274     function y=foo(a,b,c),y=a+2*b+c,endfunction
275     path=help_skeleton('foo',TMPDIR)
276     scipad(path)
277   </programlisting>
278   </refsection>
279
280   <refsection>
281     <title>Ver Também</title>
282
283     <simplelist type="inline">
284       <member><link linkend="apropos">apropos</link></member>
285
286       <member><link linkend="help">help</link></member>
287
288       <member><link linkend="help_skeleton">help_skeleton</link></member>
289     </simplelist>
290   </refsection>
291 </refentry>