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)