Se não pode deslocar-se até ao fim do texto abaixo, clica aqui.

Lar  |  Mapa  |  Índice  |  Busca

Notícias | *Arca | Enlaces | Sobre LF

[an error occurred while processing this directive]

por Guido Socher (homepage) Sobre o autor: A Guido gosta Linux porque é muito de flexível e oferece muitas mais possibilidades que qualquer outro sistema operativo. *Taducido ao espanhol por: Roberto Hernando Velasco (homepage) Conteúdos: Introdução As secções MANPATH Macros de formato Os capítulos Uma página de manual de exemplo Vendo e formatando nossa página de manual Usando perl POD para gerar páginas de manual Referências Discussão sobre esse artigo

 

Escrevendo páginas de manual Resumem: Todo bom programa que se possa usar desde a shell de UNIX deveria estar documentado em sua própria página de manual. Este tutorial é uma breve introdução à criação de páginas de manual. _________________ _________________ _________________

 

Introdução

Com frequência a documentação é mais importante que o próprio software, especialmente quando o autor não seja o único que vai utilizar dito software. Inclusive quando escrevo um programa que não penso publicar também escrevo sua documentação, já que vários meses depois poderia esquecer como usar o programa e com uma boa documentação saberei em poucos segundos como o fazer.

As utilidades tradicionais de Linux em linha de comandos sempre se documentaram em páginas de manual. Um simples man comando dizer-nos-á como utilizar o comando.

As vantagens das páginas de manual sobre outras formas de documentação são

1. Podem-se ver em poucos segundos num terminal Linux
2. Podem-se converter facilmente a outros formatos: HTML, PDF, Postscript, Texto,...
3. As páginas de manual não só se podem ver em janelas de terminal, senão também desde outros programas como konqueror (basta com digitar:man:comando)

 

As secções

As páginas de manual estão estruturadas em secções, da mesma forma que um livro está estruturado em capítulos. Por exemplo, existem duas páginas de manual de printf. Uma para a função de biblioteca C (secção 3) e a outra para o comando de shell (secção 1):

> whichman -0 printf
/usr/share/man/man1/printf.1.bz2
/usr/share/man/man3/printf.3.bz2

As diferentes secções são:

Secção
   1    Comandos de utente.
   2    Telefonemas ao sistema, isto é, funções
        provistas pelo kernel.
   3    *Subrutinas, isto é, funções de biblioteca.
   4    Dispositivos, isto é, ficheiros especiais no
        diretório /dev.
   5    Descrições de formato de ficheiros, e.g. /etc/passwd.
   6    Jogos, auto-explicativo.
   7    *Miscelánea, e.g. pacotes de macro, convenções.
   8    Ferramentas de administração do sistema que só
        pode executar o *superusuario.
   9    Outros.
   n    Novo documentação, que deveria se alterar para uma secção
        mais apropriada.
   l    Documentação local sobre este sistema em particular.

Desta forma com "man 1 printf" obtemos a documentação sobre o comando de shell printf e com "man 3 printf" mostrar-se-á a descrição da função de biblioteca C. Executando exactamente "man printf" plotar-se-á a página que primeiro se encontre (normalmente printf da secção 1).

Para comprovar se existem várias versões de páginas de manual pode-se utilizar o comando wichman como se mostrou anteriormente (*descargable desde minha página, ou bem digitando simplesmente "man:printf" em konqueror que devolver-nos-á:

 

MANPATH

O comando man procura as páginas de manual segundo o valor da variável de meio MANPATH. Desgraçadamente muitas distribuições Linux estabelecem esta variável de forma incorreta. Com frequência não se inclui /usr/lib/perl5/man, que contém um valioso conjunto de documentação sobre todas as funções perl . Pode acrescentá-lo a seu MANPATH (em .bashrc ou .tcshrc ou ...) assim:

Bash:
  MANPATH="/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"
  export MANPATH

Tcsh:
  setenv MANPATH "/usr/local/man:/usr/man:/usr/share/man:/usr/X11R6/man:/usr/lib/perl5/man"

Após definir a variável MANPATH pode-se provar "man Pod::Man" para ver se acede-se às páginas de Perl.  

Macros de formato

Escrever uma página de manual é muito fácil. É uma singela linguagem de composição onde as palavras-chave da linguagem de composição começam com um ponto no início da linha. Estas palavras-chave também se chamam macros. Os macros mais importantes são:

.TH -> Inicia o título/cabeceira da página de manual
.SH -> Encabeçado de secção
.#PP -> Novo parágrafo
."  -> Comentário
.TP -> *Sangrado do texto que esteja 2 linhas por embaixo desta macro

A sintaxe de .TH é:
.TH [nome do programa] [número de secção] [centro pé de página] [esquerda pé de página] [centro encabeçado]

A sintaxe .SH é:
.SH encabeçamento


A sintaxe de .#PP é muito singela. Simplesmente produz um avanço de linha.

Tenho visto que às vezes é útil incluir texto *preformateado para exemplos de código de programas. Isto se pode fazer com:

.nf
_o_texto_pré_formatado_
_vai_aqui_____
.fi

Tenhamos em conta que estas são macros groff/nroff e devido a isto não pertencem aos macros especiais de páginas de manual. No entanto, deveriam funcionar bem em todos os sistemas UNIX.

Todas os macros para formatar páginas de manual estão documentadas na página de manual telefonema groff_man(7) (Aqui se pode ver uma versão em html da página de manual groff_man(7)). Não vou explicar estas macros, senão que sugiro que se leia a página de manual de groff_man. A página groff_man está muito detalhada e contém todo o que se precisa saber.

 

Os capítulos

Dantes de começar a escrever nossa própria página deveríamos saber que as páginas de manual normalmente se estruturam em capítulos. Por convenção os possíveis encabeçamentos dos capítulos são os seguintes:

NOMEIE         Nome de secção, o nome da função ou o comando.
*SINOPSIS       Uso.
*DESCRIPCION    Descrição geral.
OPÇÕES          Descrições e parâmetros.
VALOR DEVOLVIDO Secções duas e três telefonemas a funções.
MEIO            Descreve variáveis de meio.
FICHEIROS       Ficheiros associados.
EXEMPLOS        Exemplos e conselhos.
*DIAGNOSTICOS   Normalmente usado pela secção 4 diagnósticos de dispositivos
                e interfaces.
ERROS           Secciones dois e três erros e sinais de *manejadores.
*VEASE *TAMBIEN Referências cruzadas e citas.
CONFORME A      Conformidade com regulares, se for o caso.
FALHAS          Erros e advertências.
SEGURANÇA       Aspectos de segurança a ter em conta.
outros          Se podem acrescentar cabeceiras feitas sob medida pelos autores.

(N.T. em inglês estes encabeçamentos são respectivamente NAME, SYNOPSIS, DESCRIPTION, OPTIONS, RETURN VALUES, ENVIRONMENT, FILES, EXAMPLES, DIAGNOSTICS, ERRORS, SEE ALSO, STANDARDS, BUGS, SECURITY CONSIDERATIONS)  

Uma página de manual de exemplo

Aqui temos uma página de manual de exemplo. Há que ter em conta que se precisa \- para distinguir a listra dos guiões. Digite tudo isto em seu editor de texto e o guarde como cdspeed.1.

.TH cdspeed 1  "10 de Setembro de 2003" "version 0.3" "COMANDOS DE UTENTE"
.SH NOME
cdspeed \- reduz a velocidade do cdrom para obter um tempo de acesso
mais rápido
.SH *SINOPSIS
.B cdspeed
[\-h] [\-d dispositivo] \-s velocidade
.SH *DESCRIPCION
As unidades de cdrom modernas são demasiado rápidas. Pode
levar bastantees segundos numa unidade de cdrom de velocidade 60x
começar a girar e ler dados da unidade. O resultado nestas
unidades é precisamente bem mais lento que em unidades a 8x ou 24x.
Isto é particularmente verdadeiro se só se lê ocasionalmente (e.g.
a cada 5 segundos) ficheiros pequenos. Esta utilidade limita a velocidade
e faz que a unidade responda melhor quando se acede a ficheiros pequenos.
.#PP
cdspeed também faz à unidade menos *ruidosa o que é muito
útil para escutar música no computador.
.SH OPÇÕES
.TP
\-h
apresenta um pequeno texto de ajuda
.TP
\-d
usa o dispositivo dado em lugar de /dev/cdrom
.TP
\-s
estabelece a velocidade. O argumento é um inteiro. Zero significa restaurar
à velocidade máxima
.SH EXEMPLOS
.TP
Estabelecer a velocidade máxima do cdrom a 8:
.B cdspeed
\-s 8
.#PP
.TP
Restaurar a velocidade máxima:
.B cdspeed
\-s 0
.#PP
.SH ESTADO DE SAÍDA
cdspeed devolve um zero se consegue mudar a velocidade máxima da
unidade de cdrom à estabelecida. Devolve-se não zero em caso de falha.
.SH AUTOR
Guido Socher (guido (at) linuxfocus.org)
.SH *VEASE *TAMBIEN
eject(1)

Pulse aqui (cdspeed.html) para ver a página anterior (N.T. em sua versão inglesa).  

Vendo e formatando nossa página de manual

Enquanto escrevemos a página de manual podemos ir vendo de vez em quando que aspecto tem. Digitando:

nroff -man nossa_página_de_manual.1 | less

ou

groff -man -Tascii nossa_página_de_manual.1 | less

Para converter uma página de manual em texto plano *preformateado (e.g. para comprovar a ortografia) utiliza-se:

nroff -man nossa_página_de_manual.1 | col -b > xxxx.txt

Para convertê-lo em Postscript (para plotar ou para uma conversão posterior a pdf) usa-se:

groff -man -Tps nossa_página_de_manual.1 > nuestra_página_de_manual.ps

Pode-se converter a página de manual a html mediante:

man2html nossa_página_de_manual.1

 

Usando perl POD para gerar páginas de manual

Sei que a muitos estar-lhes-á a estranhar o facto de só poder editar a página de manual num editor de texto. O que querem é gerar a página de manual. O formato de documentação POD de perl é uma boa eleição. Podemos escrever a página em sintaxe POD e então executar o comando

pod2man nuestra_página_de_manual.pod > nossa_página_de_manual.1

A sintaxe da linguagem de documentação pod de perl descreve-se numa página de manual telefonema perl pod. A página de manual do exemplo anterior poder-se-ia ver em formato pod como se mostra a seguir. Há que ter em conta que POD é *sensitivo aos espaços pelo que as linhas em alvo ao redor de "=head" são necessárias.

=head1 NOME

cdspeed -  reduz a velocidade do cdrom para obter um tempo de acesso
           mais rápido

=head1 *SINOPSIS

cdspeed [-h] [-d dispositivo] -s velocidade

=head1 *DESCRIPCION

As unidades de cdrom modernas são demasiado rápidas. Pode
levar bastantees segundos numa unidade de cdrom de velocidade 60x
começar a girar e ler dados da unidade. O resultado nestas
unidades é precisamente bem mais lento que em unidades a 8x ou 24x.
Isto é particularmente verdadeiro se só se lê ocasionalmente (e.g.
a cada 5 segundos) ficheiros pequenos. Esta utilidade limita a velocidade
e faz que a unidade responda melhor quando se acede a ficheiros pequenos.

cdspeed também faz à unidade menos *ruidosa o que é muito
útil para escutar música no computador.

=head1 OPÇÕES

B<-h> apresenta um pequeno texto de ajuda

B<-d> usa o dispositivo dado em lugar de /dev/cdrom

B<-s> estabelece a velocidade. O argumento é um inteiro. Zero significa restaurar
à velocidade máxima

=head1 EXEMPLOS

Estabelecer a velocidade máxima do cdrom a 8:

          cdspeed -s 8

Restaurar a velocidade máxima:

          cdspeed -s 0


=head1 ESTADO DE SAÍDA

cdspeed devolve um zero se consegue mudar a velocidade máxima da
unidade de cdrom à estabelecida. Devolve-se não zero em caso de falha.

=head1 AUTOR

Guido Socher

=head1 *VEASE *TAMBIEN

eject(1)

 

Referências

• Man-page HOWTO
• groff_man(7), man-page macros

 

Formulário de "*talkback" para este artigo

A cada artigo tem sua própria página de "*talkback". Através dessa página podes enviar um comentário ou consultar os comentários de outros leitores

Ir à página de "*talkback"

---

Contactar com a equipa de LinuFocus © Guido Socher, FDL Linuxfocus.org

Informação sobre a tradução: em --> -- : Guido Socher (homepage) em --> es: Roberto Hernando Velasco (homepage)

2003-11-24, generated by lfparser version 2.34