Manpages

NOME

man − macros de formatação de páginas de manual

SINOPSE

groff −Tascii −man arquivo ...

groff −Tps −man arquivo ...

man [seção] título

DESCRIÇÃO

Esta página descreve o pacote de macros groff tmac.an (freqüentemende chamado man ) e outras convenções para a criação de páginas de manual. Este pacote deve ser usado por programadores ao escrever ou portar manuais para o linux. É razoavelmente compatível com outras versões do mesmo pacote, de modo que portar as páginas não deve ser difícil. Há exceções como o NET-2 BSD, que usa um pacote de macros totalmente diferente chamado mdoc. Veja mdoc(7).

Observe que as páginas mdoc do NET-2 BSD podem ser usadas com o groff simplesmente substituindo a opção −man pela opção −mdoc −mandoc , que detectará automaticamente o pacote a ser utilizado.

PREÂMBULO

O primeiro comando de uma página de man (após os comentários) deve ser

.TH título seção data origem manual,

onde:

Para binários, use alguma coisa como GNU, NET-2, SLS Distribution, MCC Distribution.

Para chamadas de sistema, coloque a versão do kernel que você está usando: Linux 0.99.11.

Para chamadas de biblioteca, use a fonte da função: GNU, BSD 4.3, Linux DLL 4.4.1.

Observe que as páginas mdoc do BSD começam com o comando Dd , e não com TH

As seções do manual são tradicionalmetne definidas assim:

1 Comandos

Comandos que podem ser executados pelo usuário a partir de um interpretador de comandos.

2 Chamadas de sistema

Funções que têm que ser executadas pelo kernel.

3 Chamadas de biblioteca

A maioria das funções libc como qsort(3))

4 Arquivos especiais

Arquivos encontrados em /dev)

5 Formatos de arquivo e convenções

O formato de arquivos como /etc/passwd e outros arquivos legíveis.

7 Pacotes de macro e convenções

Uma descrição de sistemas de arquivos, protocolos de rede, códigos de caracteres ASCII e outros, esta e outros.

8 Comandos de administração de sistema.

Comandos como mount(8), que muitas vezes apenas o root pode executar.

9 Rotinas do kernel

Esta é uma seção obsoleta do manual. Tentou-se documentar o kernel linux aqui, mas, de fato, muito pouco foi documentado, e a documetnação existente já está desatualizada. Há fontes melhores de informação para programadores do kernel.

SEÇÕES

Seções começam com .SH seguido do nome da seção. Se o nome contiver espaços ou estiver na mesma linha que o .SH, coloque-o entre aspas. Cabeçalhos comuns e recomendados incluem: NOME, SINOPSE, DESCRIÇÃO, VALORE RETORNADO (ou VALORES RETORNADOS), STATUS DE SAÍDA, MANUSEIO DE ERROS, ERROS, OPÇÕES, UTILIZAÇÃO, ARQUIVOS, AMBIENTE, DIAGNÓSTICO, SEGURANÇA DE ACORDO COM, NOTAS, PROBLEMAS, AUTOR e VEJA TAMBÉM. Use cabeçalhos corriqueiros se possível, isto torna a compreensão mais fácil. No entanto, crie seus próprios cabeçalhos se eles contribuirem para a clareza. O único cabeçalho indispensável é NOME, que deve ser a primeira seção e ser segiudo por uma descrição do programa na linha seguinte:

.SH NOME
chess \- jogo de xadrez

É indispensável seguir este formato. Tem que haver uma barra invertida antes do traço que segue o nome do comando. Esta sintaxe é usada pelo makewhatis(8) para criar um banco de dados de descrições breves de comandos para o whatis(1) e o apropos(1)

Algumas outras seções comuns têm os seguintes conteúdos:

VALORES RETORNADOS

dá uma lista de valores que um programa ou rotina podem retornar e as condições que estes valores indicam.

STATUS DE SAÍDA

lista os valores de status de saída ou um programa e as condições que levam a estes valores. Algumas páginas usam VALORES RETORNADOS ao invés de STATUS DE SAÍDA, o que não faz diferença.

FONTES

Embora haja muitas convenções arbitrárias para as páginas de man em UNIX, os padrões de fontes são definidos pelas várias centenas de páginas específicas para linux:

Para funções, os argumentos ficam sempre em itálico, mesmo na seção SINOPSE, sendo o resto da função colocado em negrito:
int myfunction(int argc, char **argv);

Nomes de arquivo vão sempre em itálico (ex. /usr/include/stdio.h), exceto na seção SINOPSE, onde os arquivos include vão em negrito (ex., #include <stdio.h>).

Macros especiais - normalmente em caixa alta - vão em negrito (ex., MAXINT).

Ao enumerar códigos de erro, estes devem ficar em negrito (geralmente se usa a macro .TP

Qualquer referência a outra página de manual ou ao assunto da página atual vai em negrito. Se for dado um número de seção, ele vai em fonte Roman (normal) sem espaços (ex. man(7)).

Os comandos de seleção de tipo são:

Tradicionalmente, cada comando tem até seis argumentos, mas as implementações GNU removeram esta limitação (você pode mantê-la se for necessário para portabilidade). Os argumentos são separados por espaços. Aspas duplas podem ser usadas para especificar um argumento que contenha espaços. Todos os argumentos serão impresoss lado a lado sem espaços, de modo que o comando .BR possa ser usado para especificar uma palavra em negrito seguida por pontuação em romano. Se não houver argumentos, o comando se aplica à linha seguinte do texto.

OUTRAS MACROS E CADEIAS DE CARACTERES

Seguem outras macros e cadeia de caracteres relevantes. Todas as macros introduzem uma quebra (terminam a linha atual do texto) Muitas destas macros usam ou definem o valor da indentação O "valor da identação" é definido por qualquer macro que tenha o parâmetro i As macros podem omitir i e o valor pré-existente será usado. Conseqüentemente, vários parágrafos podem usar a mesma indentação sem que este valor tenha que ser especificado a cada vez. Um parágrafo normal - sem indentação - usa o valor padrão de indentação de 0.5 polegada. A indentação é medida em ens. Use ens ou ems como unidade, porque elas são ajustadas automaticamente quando se muda o tamanho da fonte. As outras macros principais são:

Parágrados normais

Indentação relativa à margem

Indented Paragraph Macros

Macros de hyperlink

Outras macros

Strings pré-definidas
O pacote man tem as seguintes strings pré-definidas:

SUBCONJUNTO SEGURO

Embora o man seja tecnicamente um pacote de macros troff, muitos programas que processam páginas de manual não implementam todos os recursos do troff. Portanto, é melhor evitar os recursos mais exóticos para que eles funcionem corretamente. Evite os preprocessadores troff. Se isto for inevitável, use o tbl(1), mas com os comandos IP e TP para tabelas de duas colunas. Evite usar cálculos: a maioria dos programas não os entende. Use comandos simples, fáceis de traduzir. As seguintes macros são consideradas seguras, embora muitas vezes sejam ignoradas pelos tradutores: \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr.

Pode-se também usar as seqüências de escape troff (que começam com \). Para incluir uma barra invertida como texto, use \e. Outras seqüências (x ou xx são caracteres e N é um dígito): \’, \’, \-, \., \", \%, \*x, \*(xx, \(xx, \$N, \nx, \n(xx, \fx, e \f(xx. Evite desenhar com as seqüências de escape.

Não use o parâmetro opcional de bp (’break page’ - quebra de página). Use apenas valores positivos para sp (espaço vertical). Não defina uma macro (de) com o mesmo nome de uma macro deste pacote ou do mdoc que tenha um significado diferente: é provável que estas redefinições sejam ignoradas. Toda indentação positiva (in) deve ter uma indentação negativa correspondente. (É melhor, no entanto, usar as macros RS e RE ). O teste condicional (if,ie) deve ter apenas ’t’ ou ’n’ como condição. Apenas as traduções do tipo (tr) que puderem ser ignoradas devem ser usadas. Mudanças de fonte com (ft ou com a seqüência \f devem usar apenas os valores 1, 2, 3, 4, R, I, B, P ou CW (o comando ft também pode ser usado sem parâmetros).

Se você usar recursos que não sejam estes, confira cuidadosamente os resultados em vários programas. Se a seqüência for segura, favor informar ao mantenedor deste documento para que ele o adicione.

OBSERVAÇÕES

Procure incluir as URL ou URIs integrais no próprio texto, porque alguns programas como man2html(1) podem transformá-las automaticamente em links. Você também pode usar a macro UR para identificar links a informações relacionadas. Se você usar URLs, coloque o endereço inteiro (ex. <http://www.kernelnotes.org>;) para que os programas as encontrem automaticamente.

Programas que processem estes arquivos devem abrir o arquivo e examinar o primeiro caracter que não seja um espaço. Um ponto (.) ou aspa única (’) no começo da linha indica um arquivo tipo troff (como man ou mdoc). Um sinal de menor (<) indica um arquivo tipo SGML/XML (como HTML ou Docbook). Qualquer outra coisa indica ASCII simples (ex. saída de "catman").

Muitas páginas começam com ’\" seguido de espaço e uma lista de caracteres que prescrevem um preprocessamento para a página. Para portabilidade com tradutores não troff, recomendamos que não se use nada além do tbl(1), que o linux detecta automaticamente. No entanto, você pode desejar incluir esta informação para que sua página seja manuseada por outros sistemas menos capazes. Aqui estão as definições dos preprocessadores indicados pelos seguites caracteres:

ARQUIVOS

/usr/local/lib/groff/tmac/tmac.an
/usr/man/whatis

PROBLEMAS

A maioria das macros descreve formatação (fontes, espaçamentos...) ao invés de semântica (como: este texto é uma referência a outra página), comparado com formatos como mdoc e DocBook (então HTML tem mais marcas de semântica). Isto torna mais difícil traduzir ou tornar consistente o formato man para outros meios, dificulta ainda a inserção de referências cruzadas. Ao se limitar ao subconjuto padrão acima, a automatização da transição para outro formato de manual no futuro ficará facilitada.

A macro TX da Sun não está implementada.

AUTORES

VEJA TAMBÉM

apropos(1), groff(1), man(1), man2html(1), mdoc(7), mdoc.samples(7), whatis(1).

TRADUZIDO POR LDP-BR em 21/08/2000.

Paulo César Mendes <drps [AT] ism.br> (tradução) André L. Fassone Canova <lonelywolf [AT] blv.br> (revisão)