help_from_sci Geração de arquivos de ajuda e de arquivos de demonstração a partir da seção de comentários de cabeçalho de um arquivo-fonte .sci

## Seqüência de Chamamento

                help_from_sci() // gera um modelo de função vazio
                help_from_sci(funname,helpdir) // gera helpdir/funname.xml a partir de funname.sci
                help_from_sci(dirname,helpdir) // processa dirname/*.sci e cria helpdir/*.xml.
                help_from_sci(dirname,helpdir,helpdir) // como acima, mas também cria o arquivo de demonstração helpdir/*.dem.sce.
                [helptxt,demotxt]=help_from_sci(funname) // retorna funname.xml e funname.dem.sce como duas matrizes de texto.

## Parâmetros

funname:

  o nome de um único arquivo .sci a ser processado

dirname:

  nome do diretório onde todos os arquivos .sci serão processados

helpdir:

  endereço opcional onde o arquivo de ajuda .xml será criado

demodir:

  endereço opcional onde os arquivos de demonstração .dem.sce serão criados baseados nos códigos da seção Examples

helptxt:

  retorna o código da ajuda XML se helpdir for vazio, ou o endereço para o novo arquivo .xml

demotxt:

  retorna o código de demonstração se demodir for vazio, ou o endereço para o novo arquivo .dem.sc

## Descrição

help_from_sci é uma versão revisada da função help_skeleton. Seu objetivo é gerar arquivos de ajuda .xml baseados na seção de comentários de cabeçalho dos arquivos-fontes .sci. Opcionalmente, os arquivos de demonstração .dem.sce podem ser gerados baseados nos códigos da seção Examples na seção de cometários de cabeçalho dos arquivos .sci.

Para que help_from_sci formate o arquivo .xml propriamente, os a seção de comentários de cabeçalho deve concordar com algumas regras simples de formatação.

A primeira linha de comentário seguinte à definição de função deve conter uma descrição breve da função.

Os comentários restantes são formatados de acordo com os seguintes cabeçalhos (opcionais): "Syntax", "Parameters", "Description", "Examples", "See also", "Used functions", "Authors" e "Bibliography".

As seguintes diretrizes devem ser seguidas ao se escrever os comentários de código fonte:

- `Syntax` - um exemplo por linha.

- `Parameters` - separe o nome do parâmetro e a descrição por um ":". Mantenha a descrição de cada parâmetro na mesma linha.

- `Description` - 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.

- `See also` - liste um nome de função por linha.

- `Authors` - escreva um autor em cada linha após o cabeçalho Authors. Use ";" para separar os autores de qualquer informação adicional.

- `Bibliography` - escreva uma referência por linha seguindo o cabeçalho References.

The "&" character as well as numerical HTML entities like "&#123;" are supported in the contents. Literal HTML entities like "&acute;" are not accepted. Please use directly the UTF-8 character like "é" instead.

## Exemplos

    help_from_sci()   // abrindo um modelo de código-fonte vazio no editor.
    // salve este modelo como test_fun.sci no diretório corrente antes de executar
    // os próximos comandos do exemplo

    help_from_sci('test_fun')        // retornando o esqueleto xml como um string de texto.

    help_from_sci('test_fun','.')    // criando o arquivo de ajuda xml no diretório corrente.

    // criando ambos os arquivos de ajuda e demonstração no diretório corrente.
    help_from_sci('test_fun','.','.')

    // de um diretório raiz de um toolbox, uma seqüência de chamamento típica seria:
    // help_from_sci('macros','help\pt_BR','demos')
    // este comando processaria todos os arquivos .sci no diretório de macros
    // e utilizaria a seção de comentários de cabeçalho para atualizar as ajudas .xml no
    // diretório help\en_US e reconstruiria os arquivos .dem.sce no diretório demos\.

## Ver Também

- help
- help_skeleton
- xmltohtml

## Histórico

6.0.1 Numerical HTML entities like `&#969;` are now accepted in heading comments. However, writting directly UTF-8 characters should be preferred.