Provided by:
manpages-pt_20040726-4_all 
NOME
man - macros de formatação de páginas de manual
SINOPSE
groff -Tascii -man arquivo ...
groff -Tps -man arquivo ...
man [seo] ttulo
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 ttulo seo data origem manual,
onde:
ttulo o título da página (ex., MAN).
seo 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
seo 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)