Name

man — Descrição do formato do arquivo de ajuda XML

Descrição

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 .

Breves palavras sobre XML

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.

Como escrever uma página de ajuda XML do Scilab simples: a maneira lazzy

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.

Como escrever uma página de ajuda XML do Scilab simples: um exemplo

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>
 

Como criar um capítulo de ajuda

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) .

Como fazer o Scilab reconhecer um novo capítulo de ajuda

Isto pode ser feito através da função add_help_chapter.

Exemplos

    function y=foo(a,b,c),y=a+2*b+c,endfunction
    path=help_skeleton('foo',TMPDIR)
    if (isdef('editor') | (funptr('editor')<>0)) then
      editor(path)
    end
  

Ver Também

apropos, help, help_skeleton