DOKK / manpages / debian 10 / manpages-pt / man.7.pt
MAN(7) Manual do Programador Linux MAN(7)

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

groff -Tascii -man arquivo ...

groff -Tps -man arquivo ...

man [seção] título

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.

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:
título
o título da página (ex., MAN).
O número da seção na qual a página deve ser colocada (ex. 7).
A data da última revisão (emlembre-se de alterar isto toda vez que uma alteração é feita na página de manual, visto que isto é a forma mais geral de fazer um controle de versão.
A origem do comando.

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.

O título do manual (e.g., Manual do Programador Linux).

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.
6 Jogos
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 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:

descreve sucintamente a interface do comando ou função. Para comandos, mostra a sintaxe do comando e seus argumentos, incluindo as opções; Usa-se texto em negrito para as opções fixas, e itálico para indicar argumentos substituíveis. Colchetes ([]) cercam argumentos opcionais, barras verticais (||) separam opções, e elipses (...) indicam ser possível repetição. Para funções, inclui ainda declarações de dados necessárias ou cabeçalhos ou diretivas #include ; que são seguidas pela declaração da função.
descreve o que a função, comando ou formato fazem. Discute sua interação com arquivos e com o stdin, e o que é enviado para o stdout ou stderr. Detalhes do funcionamento interno ou implementação são omitidos a não ser que sejam vitais para se entender a interface. Procure descrever utilizações comuns. Para informação sobre as opções, use a seção OPÇÕES Se houver algum tipo formato específico ou conjunto de subcomandos, talvez valha a pena descrevê-los numa seção UTILIZAÇÃO separada e colocar uma visão geral na seção DESCRIÇÃO
dá uma lista de valores que um programa ou rotina podem retornar e as condições que estes valores indicam.
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.
descreve as opções que o programa aceita e como elas afetam seu comportamento.
descreve a gramática de qualquer sublinguagem que ele implementar.
lista os arquivos usados pelo programa ou função, tais como arquivos de configuração, arquivos de inicialização e arquivos com os quais o programa trabalhe diretamente. Dê o caminho completo destes arquivos, e use o processo de instalação para modificar o diretório conforme seja conveniente. Para muitos programas, a instalação padrão é em /usr/local, e sua página de manual deverá usar /usr/local como base.
lista todas as variáveis de ambiente que afetam seu programa ou função e o modo como elas o fazem.
dá uma visão das mensagens de erro mais comuns e de como lidar com elas. Você não precisa explicar erros do sistema ou sinais fatais que podem aparecer durante a execução a menos que elas afetem seu programa de um modo especial.
discute assuntos e implicaçÕes de segurança. Avise sobre configurações ou ambientes que devam ser evitados, comandos que possam ter implicações de segurança e assim por diante, especialmente se não forem óbvias. Uma seção de seguraça não é necessária se a informação for fácil de entender e puder ser colocada em outras seções como DESCRIÇÃO ou UTILIZAÇÃO Mas não deixe de inlcuir a informação de segurança!
descreve normas ou convenções implementadas.
contém outras observações
lista limitações, defeitos, inconveniência e outros comportamentos indesejáveis.
lista os autores da documentação ou do programa para que você possa enviar relatórios de bugs.
lista as páginas de manual relacionadas em ordem alfabética, podendo ser seguida por outras páginas ou documentos. Normalmente é a última seção.

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:

.B
Negrito
.BI
Negrito alternando com itálico (usado em especificação de funções)
.BR
Negrito alternando com Roman (usado para referência a outras páginas de manual)
.I
Itálico
.IB
Itálico alternando com negrito
.IR
Itálico alternando com Roman
.RB
Roman alternando com negrito
.RI
Roman alternando com itálico
.SB
Pequeno alternnado com negrito
.SM
Pequeno (usado para siglas)

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.

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:

.LP
Assim como .PP (começar novo parágrafo).
.P
Assim como .PP (começar novo parágrafo).
.PP
Começar novo parágrafo e reinicializar a indentação.

.RS i
Iniciar indentação relativa à margem: move a margem esquerda i para a direita. (Se o i for omitido, é usado o valor atual de indentação. Uma indentação é inicializada em 0.5 polegada. Conseqüentemente, todos os parágrafos seguintes serão indentados até o correspondente .RE.
.RE
Termina a indentação de margem relativa e restaura os valores anteriores de indentação.

.HP i
Begin paragraph with a hanging indent (the first line of the paragraph is at the left margin of normal paragraphs, and the rest of the paragraph's lines are indented).
.IP x i
Indented paragraph with optional hanging tag. Se o tag x for omitido, o parágrafo seguinte inteiro é indentado com i. Se houver o tag x , ele é colocado na margem esquerda antes do parágrafo indentado seguinte, da mesma forma que o .TP, exceto que o tag é incluído com o comando ao invés de na linha seguinte. Se o tag for muito longo, o texto que o segue será colocado na linha seguinte, não havendo perdas ou distorção. Para listas de itens, usa esta macro com \(bu (de 'bullet' - bolinha) ou \(em (traço) como tag. Para listas numeradas, use o número ou letra seguido por um ponto como tag. Isto facilita a tradução para outros formatos.
.TP i
Inicia um parágrafo com um tag pendente. O tag é dado na linha seguinte, mas o resultado é o mesmo do comando .IP
.UR u
inicia um hyperlinx para uma URI (URL) u; e termina com o comando UE correspondente. Ao se gerar HTML, deve se tornar o comando <A HREF="u">. Há uma exceção: se u tiver o valor ":", não será gerado nenhum link de hipertexto até o UE final. Isto permite desabilitar hyperlinks em frases como LALR(1) onde os links não são apropriados. Estas "macros" de hipertexto são novas, e muitos programas não farão nada com elas. Mas como muitos programas - inclusive o troff - simplesmente ignoram macros não definidas (ou na pior das hipóteses inclui estas macros como texto), é seguro utilizá-las.
.UE
finaliza o comando UR correspondente. Ao gerar HTML, isto deve ser traduzido como </A>.
.UN u
Cria um local de hipertexto chamado u; não é necessário incluir um UE correspondente. Ao gerar HTML, isto deve ser traduzido como <A NAME="u" id="u">&nbsp;</A> (O &nbsp; é opcional se não for necessário suporte ao Mosaic).

.DT
Reinicializa a indentação com os valroes padrão (a cada 0.5 polegada) sem introduzir uma quebra.
.IX ...
Introduz um índice (para um sistema de busca ou índice impresso). Esta informação normalmente não é exibida na página. É seguida por um único parâmetro, que é acrescentado como um único termo apontando para uma dada localização na página. Se houverem dois parâmetros, normalmente está no formato Perl manpage: o primeiro designa o tipo do nome (pode ser Nome, Titilo, Cabeçalho, Subseção ou Ítem) e o segundo parâmetro indica o nome a ser indexado. Caso contrário, está no formato de índice longo: cada parâmetro dá um termo de índice, termo de índice subordinado, termo de índice subsubordinado e assim por diante até que se encontre um parâmetro vazio, um parâmetro com o nome do programa (\em) e uma descrição breve. Isto pode ser seguido por outro parâmetro vazio e talvez por mensagens de controle de página como 'PAGE START'. Um exemplo seria: "programming tools" "make" "" "\fLmake\fP \(em build programs".
.PD d
Ajusta a distância entre parágrafos para d (se omitido, d=0.4v). Não introduz quebra.
.SS t
Subcabeçalho t (mesmo que .SH, mas usado para subseções dentro de uma seção.

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

\*R
Marca registrada: ®
\*S
Mudar para tamanho de fonte padrão
\*(Tm
Marca: (Tm)
\*(lq
Aspas anguladas (esquerda): “
\*(rq
Aspas anguladas (direita): ”

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.

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:

eqn(1)
grap(1)
pic(1)
refer(1)
tbl(1)
vgrind(1)

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

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.

—
James Clark (jjc@jclark.com) escreveu a implementação do pacote de macros.
—
Rickard E. Faith (faith@cs.unc.edu) escreveu a versão inicial desta página.
—
Jens Schweikhardt (schweikh@noc.fdn.de) escreveu o Linux Man-Page Mini-HOWTO (que influenciou esta página de manual).
—
David A. Wheeler (dwheeler@ida.org) modificou consideravelmente esta página, adicionando informações detalhadas sobre seções e macros.

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

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

16/06/1999 Linux