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
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.
o nome de um único arquivo .sci a ser processado
nome do diretório onde todos os arquivos .sci serão processados
endereço opcional onde o arquivo de ajuda .xml será criado
endereço opcional onde os arquivos de demonstração .dem.sce serão criados baseados nos códigos da seção Examples
retorna o código da ajuda XML se helpdir for vazio, ou o endereço para o novo arquivo .xml
retorna o código de demonstração se demodir for vazio, ou o endereço para o novo arquivo .dem.sc
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): "Calling Sequence", "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:
Calling Sequence
- 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.
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\.