man — Descrição do formato do arquivo de ajuda XML
Os arquivos-fontes da ajuda Scilab são escritos em formato XML
Arquivos-fontes (com extensão .xml) podem ser encontrados nos
diretórios <SCIDIR>/man/<language>/*. O
nome do arquivo é geralmente associado à palavra-chave (correspondente a
um nome de função na maioria dos casos) que descreve .
Um arquivo XML lembra um arquivo HTML, mas possui uma sintaxe tanto
mais rígida quanto mais livre. Livre porque você pode construir os seus
próprios tags (marcação): o conjunto de tags, junto com suas regras, deve
ser descrito em algum lugar, geralmente em outro arquivo
(<SCIDIR>/man/manrev.dtd para o Scilab), e rígida
porque, uma vez que os tags e regras são definidas (as quais são chamadas
Definição de Tipo de Documento (Document Type Definition): DTD) , você
deve respeitá-las (em particular, para todos os tags
<MY_TAG> abertos, deve corresponder um tag
fechado </MY_TAG>).
O DTD manrev.dtd é escrito em SGML e precisa a exata sintaxe requerida por uma página de ajuda XML do Scilab. Então se você conhece esta linguagem, você pode ler este arquivo. O seguinte exemplo anotado (veja a próxima seção) mostra algumas possibilidades oferecidas por este DTD e pode ser suficiente para escrever páginas de ajuda simples.
Uma vez que a página XML é escrita e está em conformidade com o DTD,
ela pode ser transformada em um HTML para ser lida por algum navegador de
internet, ou pelo navegador tcltk do Scilab (ver a seção escolha do
navegador nesta página). A tradução XML -> HTML é controlada por um
conjunto de regras escritas no arquivo (XML)
<SCIDIR>/man/language/html.xsl. Estas regras
estão correntemente mais ou menos restritas para se adequarem aos recursos
do navegador tcltk do Scilab (que pode exibir corretamente apenas HTML
básico): Se você utilizar um navegador de HTML e quiser melhorar a
aparência, terá que modificar este arquivo.
Caso se deseje escrever um arquivo XML associado a uma nova função Scilab, pode-se utilizar a função help_skeleton para produzir o esqueleto do arquivo XML. Na maior parte dos casos, o usuário não precisará saber a sintaxe XML.
Aqui está um exemplo simples de uma página de ajuda XML que descreve
uma função do Scilab hipotética chamada "foo". No seguinte, o arquivo XML
é exibido em uma fonte de máquina-de-escrever e
recortado em várias partes, cada parte precedida por algumas explicações
associadas. O arquivo XML inteiro foo.xml está no
diretório <SCIDIR>/man/eng/utility e o resultado
pode ser exibido clicando-se em foo (você pode
encontrar outros exemplos no diretório
<SCIDIR>/examples/man-examples-xml). Finalmente note que alguns pares de tags
<TAG>, </TAG> foram
renomeados aqui <ATAG>,
</ATAG>. Isto porque alguns scripts do Scilab que
realizam trabalhos sobre ou a partir dos arquivos XML não verificam se um
tag está dentro de uma entrada VERBATIM.
As primeiras três linhas do arquivo são mandatórias, a segunda
precisa o endereço para o arquivo DTD e a terceira, formada pelo tag
<MAN>, inicia a descrição hierárquica (o arquivo
deve terminar com o tag </MAN>). As quatro
entradas seguintes : LANGUAGE,
TITLE, TYPE e
DATE, também são mandatórias (nesta ordem), o texto
correspondente a <TYPE> sendo geralmente 'função
do Scilab' (na maior parte dos casos), mas pode ser simplesmente
'palavra-chave do Scilab' ou 'tipo de dados do Scilab', ..., dependendo do
que explica a página de ajuda.
<!DOCTYPE MAN SYSTEM "<SCIDIR>/man/manrev.dtd"> <MAN> <LANGUAGE>eng</LANGUAGE> <TITLE>foo</TITLE> <TYPE>função do Scilab</TYPE> <DATE>$LastChangedDate$</DATE>
A primeira destas duas entradas seguintes
(SHORT_DESCRIPTION) é mandatória e importante desde que
as palavras do texto da descrição curta (short description), são
utilizadas pelo comando apropos para buscar
páginas de ajuda a partir de uma palavra-chave: a descrição curta é
utilizada para construir o arquivo whatis.html
correspondente ao seu toolbox e o comando apropos
keyword faz uma pesquisa em todos os arquivos whatis e propõe os
links para cada página onde a palavra keyword se
encontra em sua descrição curta (na verdade, os tags reais associados são
<SHORT_DESCRIPTION> e
</SHORT_DESCRIPTION> e não
<ASHORT_DESCRIPTION> e
</ASHORT_DESCRIPTION>). A próxima entrada
(CALLING_SEQUENCE) deve ser utilizada ao se descrever
uma função (mas não é estritamente mandatória). Se a sua função possui
várias seqüências de chamamento, utilize várias entradas
CALLING_SEQUENCE_ITEM.
<ASHORT_DESCRIPTION name="foo">descrição curta de foo</ASHORT_DESCRIPTION>
<CALLING_SEQUENCE>
<CALLING_SEQUENCE_ITEM>[y] = foo(x)</CALLING_SEQUENCE_ITEM>
</CALLING_SEQUENCE>
A entrada seguinte (PARAM) não é estritamente
mandatória, mas é a boa para descrever cada parâmetro (de entrada e saída)
no caso de uma função.
<PARAM>
<PARAM_INDENT>
<PARAM_ITEM>
<PARAM_NAME>x</PARAM_NAME>
<PARAM_DESCRIPTION>
<SP>: o que pode ser x</SP>
</PARAM_DESCRIPTION>
</PARAM_ITEM>
<PARAM_ITEM>
<PARAM_NAME>y</PARAM_NAME>
<PARAM_DESCRIPTION>
<SP>: o que pode ser y</SP>
</PARAM_DESCRIPTION>
</PARAM_ITEM>
</PARAM_INDENT>
</PARAM>
A entrada DESCRIPTION é talvez a mais
significativa (mas não é estritamente mandatória) e pode ser mais
sofisticada que neste exemplo (por exemplo, você pode ter sub-entradas
DESCRIPTION_ITEM). Aqui, você vê como escrever vários
parágrafos (cada um encerrado pelos tags <P> e
</P>), como enfatizar uma variável, ou um nome de
função (encerrando-os por tags <VERB> e
</VERB>), como enfatizar uma parte o texto
(<EM> ou <BD> e
<TT> para colocar em fonte de máquina de
escrever)), e, finalmente, como colocar um link para outra página de ajuda
(na verdade, os tags associados são <LINK> e
</LINK> e não <ALINK> e
</ALINK>).
<DESCRIPTION>
<P>
Um primeiro parágrafo explica o que a função foo computa.
Se você deseja enfatizar um nome de parâmetro, você pode utilizar o segunte
tag <VERB>x</VERB>, se você desejar enfatizar parte do texto
<EM>encerre-a nestes tags</EM> e use estes
<BD>para uma fonte em negrito</BD> e finalmente <TT>para um estilo em máquina de escrever</TT>.
</P>
<P>
Um segundo parágrafo... Aqui vai um exemplo de um link para outra página :
<ALINK>man</ALINK>.
</P>
</DESCRIPTION>
Aqui está como escrever a sua própria entrada, por exemplo, para escrever observações e/ou notas sobre a sua maravilhosa função.
<SECTION label='Notes'>
<P>
Aqui está uma lista de notas :
</P>
<ITEM label='first'><SP>blablabla...</SP></ITEM>
<ITEM label='second'><SP>toto é o francês de foo...</SP></ITEM>
</SECTION>
Uma entrada importante é EXAMPLE que é reservada
para mostrar usos no Scilab da sua função (comece com exemplos simples!).
Note que você deve fechar esta entrada com
]]></EXAMPLE> , e não como aqui com
}}></EXAMPLE> (mais uma vez, este é um truque
ruim para evitar problemas de interpretação).
<EXAMPLE><![CDATA[
deff("y=foo(x)","y=x"); // definindo a função foo como a função identidade
foo("toto")
}}></EXAMPLE>
Esta última parte explica como colocar links para outras páginas de
ajuda relacionadas (como já foi dito antes, os bons tags são
<LINK> e </LINK> e não
<ALINK> e </ALINK> ) e
finalmente como revelar o seu nome, se você quiser (utilize uma entrada
AUTHOR_ITEM por autor). Talvez seja uma boa idéia
colocar um endereço de email, se você procura por relatos de bugs !
<SEE_ALSO> <SEE_ALSO_ITEM> <ALINK>man</ALINK> </SEE_ALSO_ITEM> <SEE_ALSO_ITEM> <ALINK>apropos</ALINK> </SEE_ALSO_ITEM> </SEE_ALSO> <AUTHOR> <AUTHOR_ITEM>B. P.</AUTHOR_ITEM> </AUTHOR> </MAN>
Crie um diretório e escreva um conjunto de arquivos XML construídos
como descrito acima. Então, inicie o Scilab e execute
xmltohtml(dir), onde é um dir string
fornecendo o endereço do diretório (ver xmltohtml para mais detalhes) .
Isto pode ser feito através da função add_help_chapter.