help_from_sci

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 "{" are supported in the contents. Literal HTML entities like "´" 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 — comando de ajuda on-line
• help_skeleton — constrói o esqueleto do arquivo de ajuda xml associado à função Scilab
• xmltohtml — converte arquivos de ajuda xml do Scilab para formato HTML

Histórico