Provided by: manpages-pt_20040726-5_all 
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:
título o título da página (ex., MAN).
seção O número da seção na qual a página deve ser colocada (ex. 7).
data 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.
origem 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.
manual 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
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:
SINOPSE 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.
DESCRIÇÃ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
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.
OPÇÕES descreve as opções que o programa aceita e como elas afetam seu comportamento.
UTILIZAÇÃO descreve a gramática de qualquer sublinguagem que ele implementar.
ARQUIVOS 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.
AMBIENTE lista todas as variáveis de ambiente que afetam seu programa ou função e o modo como elas o
fazem.
DIAGNÓSTICO 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.
SEGURANÇA 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!
DE ACORDO COM descreve normas ou convenções implementadas.
OBSERVAÇÕES contém outras observações
PROBLEMAS lista limitações, defeitos, inconveniência e outros comportamentos indesejáveis.
AUTOR lista os autores da documentação ou do programa para que você possa enviar relatórios de
bugs.
VEJA TAMBÉM 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.
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:
.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.
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
.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.
Indentação relativa à margem
.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.
Indented Paragraph Macros
.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
Macros de hyperlink
.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"> </A> (O é opcional se não for
necessário suporte ao Mosaic).
Outras macros
.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.
Strings pré-definidas
O pacote man tem as seguintes strings pré-definidas:
\*R Marca registrada: ®
\*S Mudar para tamanho de fonte padrão
\*(Tm Marca: ™
\*(lq Aspas anguladas (esquerda): “
\*(rq Aspas anguladas (direita): ”
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:
e eqn(1)
g grap(1)
p pic(1)
r refer(1)
t tbl(1)
v vgrind(1)
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
— 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.
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@ism.com.br> (tradução) André L. Fassone Canova <lonelywolf@blv.com.br> (revisão)
Linux 16/06/1999 MAN(7)