.\" -*- nroff -*-
.\" (C) Copyright 1992-1999 Rickard E. Faith e David A. Wheeler
.\" (faith@cs.unc.edu e dwheeler@ida.org)
.\"
.\" Garante-se permisso para fazer e distribuir cpias exatas deste manual
.\" conqanto a nota de copyright e esta permisso sejam mantidas.
.\"
.\" Garante-se permisso para fazer e distribuir verses modificadas deste manual
.\" sob as mesmas condies para as cpias exatas, conqanto o trabalho resultante
.\" seja distribudo sob os termos de permisso idnticos a este.
.\" 
.\" Como o kernel linux e suas bibliotecas mudam constantemente, esta pgina
.\" pode se tornar incorreta ou desatualizada. O(s) autor(es) no assumem
.\" qualquer responsabilidade por erros ou omisses, ou por danos que resultem
.\" do uso da informao aqui contida. O(s) autor(es) podem no ter trabalhado
.\" neste manual - que  gratuito - com o mesmo esmero com que trabalham 
.\" profissionalmente.
.\" 
.\" Verses processadas ou formatadas deste manual, se no forem acompanhadas pelo
.\" cdigo fonte, tm que reconhecer os autores e o direito autoral.
.\"
.\" Modificado Sb Jul 25 11:06:05 1993 por Rik Faith (faith@cs.unc.edu)
.\" Modificado Sb Jun  8 00:39:52 1996 por aeb
.\" Modificado Qua Jun 16 23:00:00 1999 por David A. Wheeler (dwheeler@ida.org)
.\" Modificado Qui Jul 15 12:43:28 1999 por aeb
.\" [a fazer: dividir esta pgina em man.7 (descries das macros) e manpage.7
.\" descrevendo as convenes linux de pginas de manual] 
.\"
.TH MAN 7 "16/06/1999" "Linux" "Manual do Programador Linux"
.SH NOME
man \- macros de formatao de pginas de manual
.SH SINOPSE
.B groff \-Tascii \-man
.I arquivo
\&...
.LP
.B groff \-Tps \-man
.I arquivo
\&...
.LP
.B man
.RI [ seo ]
.I ttulo
.SH DESCRIO
Esta pgina descreve o pacote de macros
.B "groff tmac.an"
(freqentemende chamado 
.B man
)  e outras convenes para a criao de pginas de manual.
Este pacote deve ser usado por programadores ao escrever
ou portar manuais para o linux.  razoavelmente compatvel
com outras verses do mesmo pacote, de modo que portar as pginas no
deve ser difcil. H excees como o NET-2 BSD, que usa um pacote de
macros totalmente diferente chamado mdoc. Veja
.BR mdoc (7).
.PP
Observe que as pginas mdoc do NET-2 BSD podem ser usadas com o
.B groff
simplesmente substituindo a opo
.B \-man
pela opo
.B \-mdoc
.   recomendvel, no entanto, usar a opo
.B \-mandoc
, que detectar automaticamente o
pacote a ser utilizado.
.SH PREMBULO
O primeiro comando de uma pgina de man (aps os comentrios) deve ser
.RS
.sp
.B \&.TH
.IR "ttulo seo data origem manual" ,
.sp
.RE
onde:
.RS
.TP 10
.I ttulo
o ttulo da pgina (ex.,
.IR MAN ).
.TP
.I seo
O nmero da seo na qual a pgina deve ser colocada (ex.
.IR 7 ).
.TP
.I data
A data da ltima reviso (emlembre-se de alterar isto toda vez que
uma alterao  feita na pgina de manual, visto que isto  a forma mais geral de fazer
um controle de verso.
.TP
.I origem
A origem do comando.
.sp
Para binrios, use alguma coisa como
.IR GNU ", " NET-2 ", " "SLS Distribution" ", " "MCC Distribution" .
.sp
Para chamadas de sistema, coloque a verso do kernel que voc
est usando:
.IR "Linux 0.99.11" .
.sp
Para chamadas de biblioteca, use a fonte da funo:
.IR GNU ", " "BSD 4.3" ", " "Linux DLL 4.4.1" .
.TP
.I manual
O ttulo do manual (e.g.,
.IR "Manual do Programador Linux" ).
.RE
.PP
Observe que as pginas mdoc do BSD comeam com o comando
.B Dd
, e no com
.B TH
.
.PP
As sees do manual so tradicionalmetne definidas assim:
.RS
.TP 10
.B 1 Comandos
Comandos que podem ser executados pelo usurio a partir de
um interpretador de comandos.
.TP
.B 2 Chamadas de sistema
Funes que tm que ser executadas pelo kernel.
.TP
.B 3 Chamadas de biblioteca
A maioria das funes
.I libc
como
.BR qsort (3))
.TP
.B 4 Arquivos especiais
Arquivos encontrados em
.IR /dev )
.TP
.B 5 Formatos de arquivo e convenes
O formato de arquivos como
.I /etc/passwd
e outros arquivos legveis.
.TP
.B 6 Jogos
.TP
.B 7 Pacotes de macro e convenes
Uma descrio de sistemas de arquivos, protocolos de rede,
cdigos de caracteres ASCII e outros, esta e outros.
.TP
.B 8 Comandos de administrao de sistema.
Comandos como
.BR mount (8),
que muitas vezes apenas o
.I root
pode executar.
.TP
.B 9 Rotinas do kernel
Esta  uma seo obsoleta do manual.
Tentou-se documentar o kernel linux aqui,
mas, de fato, muito pouco foi documentado, e a documetnao
existente j est desatualizada. H fontes melhores de informao para
programadores do kernel.
.RE
.SH SEES
Sees comeam com
.B \&.SH
seguido do nome da seo. Se o nome contiver espaos ou estiver na mesma
linha que o
.BR \&.SH ,
coloque-o entre aspas. Cabealhos comuns
e recomendados incluem:
NOME, SINOPSE, DESCRIO, VALORE RETORNADO (ou VALORES RETORNADOS),
STATUS DE SADA, MANUSEIO DE ERROS, ERROS,
OPES, UTILIZAO, ARQUIVOS, AMBIENTE, DIAGNSTICO, SEGURANA
DE ACORDO COM, NOTAS,
PROBLEMAS, AUTOR e VEJA TAMBM.
Use cabealhos corriqueiros se possvel,
isto torna a compreenso mais fcil.
No entanto, crie seus prprios cabealhos se eles contribuirem
para a clareza.
O nico cabealho indispensvel 
.IR NOME ,
que deve ser a primeira seo e
ser segiudo por uma descrio do programa na linha seguinte:
.RS
.sp
\&.SH NOME
.br
chess \\- jogo de xadrez
.sp
.RE
 indispensvel seguir este formato. Tem que haver uma
barra invertida antes do trao que segue o nome do comando. Esta
sintaxe  usada pelo 
.BR makewhatis (8)
para criar um banco de dados de descries breves de comandos para o
.BR whatis (1)
e o
.BR apropos (1)
.
.PP
Algumas outras sees comuns tm os seguintes contedos:
.TP 14
.B SINOPSE
descreve sucintamente a interface do comando ou funo.
Para comandos, mostra a sintaxe do comando e seus argumentos,
incluindo as opes;
Usa-se texto em negrito para as opes fixas, e itlico para indicar 
argumentos substituveis. Colchetes ([]) cercam argumentos opcionais,
barras verticais (||) separam opes, e elipses (\&...) indicam ser possvel repetio.
Para funes, inclui ainda declaraes de dados necessrias ou cabealhos ou diretivas
.B #include
; que so seguidas pela declarao da funo.
.TP
.B DESCRIO
descreve o que a funo, comando ou formato fazem.
Discute sua interao com arquivos e com o stdin, e o que
 enviado para o stdout ou stderr.
Detalhes do funcionamento interno ou implementao so omitidos a no ser
que sejam vitais para se entender a interface.
Procure descrever utilizaes comuns. Para informao sobre as opes, use a seo
.B OPES
.
Se houver algum tipo formato especfico ou conjunto de subcomandos, talvez
valha a pena descrev-los numa seo
.B UTILIZAO
separada e colocar uma viso geral na seo
.B DESCRIO
.
.TP
.B VALORES RETORNADOS
d uma
lista de valores que um programa ou rotina podem retornar e as condies
que estes valores indicam.
.TP
.B STATUS DE SADA
lista os valores de status de sada ou um programa
e as condies que levam a estes valores.
Algumas pginas usam VALORES RETORNADOS ao invs de STATUS DE SADA,
o que no faz diferena.
.TP
.B OPES
descreve as opes que o programa aceita e como elas afetam
seu comportamento.
.TP
.B UTILIZAO
descreve a gramtica de qualquer sublinguagem que ele implementar.
.TP
.B ARQUIVOS
lista os arquivos usados pelo programa ou funo, tais como
arquivos de configurao, arquivos de inicializao
e arquivos com os quais o programa trabalhe diretamente.
D o caminho completo destes arquivos, e use o processo
de instalao para modificar o diretrio conforme seja conveniente.
Para muitos programas, a instalao padro  em /usr/local, e sua pgina de
manual dever usar /usr/local como base.
.TP
.B AMBIENTE
lista todas as variveis de ambiente que afetam seu programa ou funo
e o modo como elas o fazem.
.TP
.B DIAGNSTICO
d uma viso das mensagens de erro mais comuns e de como lidar com
elas. Voc no precisa explicar erros do sistema ou sinais fatais que
podem aparecer durante a execuo a menos que elas afetem seu programa
de um modo especial.
.TP
.B SEGURANA
discute assuntos e implicaes de segurana.
Avise sobre configuraes ou ambientes que devam ser evitados, comandos
que possam ter implicaes de segurana e assim por diante, especialmente
se no forem bvias.
Uma seo de seguraa no  necessria se
a informao for fcil de entender
e puder ser colocada em outras sees como
.B DESCRIO
ou
.B UTILIZAO
.
Mas no deixe de inlcuir a informao de segurana!
.TP
.B DE ACORDO COM
descreve normas ou convenes implementadas.
.TP
.B OBSERVAES
contm outras observaes
.TP
.B PROBLEMAS
lista limitaes, defeitos, inconvenincia
e outros comportamentos indesejveis.
.TP
.B AUTOR
lista os autores da documentao ou do programa para que voc possa enviar
relatrios de bugs.
.TP
.B VEJA TAMBM
lista as pginas de manual relacionadas em ordem alfabtica, podendo ser 
seguida por outras pginas ou documentos.
Normalmente  a ltima seo.
.SH FONTES
Embora haja muitas convenes arbitrrias para as pginas de man em UNIX,
os padres de fontes so definidos pelas vrias centenas de pginas especficas
para linux:
.IP
Para funes, os argumentos ficam sempre em itlico,
.IR "mesmo na seo SINOPSE" ,
sendo o resto da funo colocado em negrito:
.RS
.BI "int myfunction(int " argc ", char **" argv );
.RE
.IP
Nomes de arquivo vo sempre em itlico (ex.
.IR "/usr/include/stdio.h" ),
exceto na seo SINOPSE, onde os arquivos include vo em negrito (ex.,
.BR "#include <stdio.h>" ).
.IP
Macros especiais - normalmente em caixa alta - vo em negrito (ex.,
.BR MAXINT ).
.IP
Ao enumerar cdigos de erro, estes devem ficar em negrito (geralmente
se usa a macro
.B \&.TP
.
.IP
Qualquer referncia a outra pgina de manual ou ao assunto da pgina
atual vai em negrito. Se for dado um nmero de seo, ele vai em fonte
Roman (normal) sem espaos (ex.
.BR man (7)).
.LP
Os comandos de seleo de tipo so:
.TP 4
.B \&.B
Negrito
.TP
.B \&.BI
Negrito alternando com itlico
(usado em especificao de funes)
.TP
.B \&.BR
Negrito alternando com Roman
(usado para referncia a outras
pginas de manual)
.TP
.B \&.I
Itlico
.TP
.B \&.IB
Itlico alternando com negrito
.TP
.B \&.IR
Itlico alternando com Roman
.TP
.B \&.RB
Roman alternando com negrito
.TP
.B \&.RI
Roman alternando com itlico
.TP
.B \&.SB
Pequeno alternnado com negrito
.TP
.B \&.SM
Pequeno (usado para siglas)
.LP
Tradicionalmente, cada comando tem at seis argumentos, mas as
implementaes GNU removeram esta limitao (voc pode mant-la
se for necessrio para portabilidade).
Os argumentos so separados por
espaos. Aspas duplas podem ser usadas para especificar um argumento que contenha
espaos. Todos os argumentos sero impresoss lado a lado
sem espaos, de modo que o comando
.B \&.BR
possa ser usado para especificar uma palavra em negrito seguida por
pontuao em romano.
Se no houver argumentos, o comando se aplica  linha seguinte
do texto.
.SH "OUTRAS MACROS E CADEIAS DE CARACTERES"
.PP
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 indentao
O "valor da identao"  definido por qualquer macro que tenha o parmetro
.I i
.
As macros podem omitir
.I i
e o valor pr-existente ser usado.
Conseqentemente, vrios pargrafos podem usar a mesma indentao sem que
este valor tenha que ser especificado a cada vez.
Um pargrafo normal - sem indentao - usa o valor padro de indentao de
0.5 polegada.
A indentao  medida em ens. Use ens ou ems como unidade, porque elas so
ajustadas automaticamente quando se muda o tamanho da fonte.
As outras macros principais so:
.SS "Pargrados normais"
.TP 9m
.B \&.LP
Assim como
.B \&.PP
(comear novo pargrafo).
.TP
.B \&.P
Assim como
.B \&.PP
(comear novo pargrafo).
.TP
.B \&.PP
Comear novo pargrafo e reinicializar a indentao.
.SS "Indentao relativa  margem"
.TP 9m
.BI \&.RS " i"
Iniciar indentao relativa  margem: move a margem esquerda
.I i
para a direita. (Se o
.I i
for omitido,  usado o valor atual de indentao.
Uma indentao  inicializada em 0.5 polegada.
Conseqentemente, todos os pargrafos seguintes sero
indentados at o correspondente
.BR \&.RE .
.TP
.B \&.RE
Termina a indentao de margem relativa e
restaura os valores anteriores de indentao.
.SS "Indented Paragraph Macros"
.TP 9m
.BI \&.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).
.TP
.BI \&.IP " x i"
Indented paragraph with optional hanging tag.
Se o tag
.I x
for omitido, o pargrafo seguinte inteiro  indentado com
.IR i .
Se houver o tag
.I x ,
ele  colocado na margem esquerda
antes do pargrafo indentado seguinte,
da mesma forma que o
.BR \&.TP ,
exceto que o tag  includo com o comando ao invs de na
linha seguinte.
Se o tag for muito longo, o texto que o segue ser colocado na linha seguinte,
no havendo perdas ou distoro.
Para listas de itens, usa esta macro com \e(bu (de 'bullet' - bolinha)  ou
\e(em (trao) como tag. Para listas numeradas, use o nmero ou letra seguido por
um ponto como tag.
Isto facilita a traduo para outros formatos.
.TP
.BI \&.TP " i"
Inicia um pargrafo com um tag pendente. O tag  dado na linha seguinte,
mas o resultado  o mesmo do comando
.B \&.IP
.
.SS "Macros de hyperlink"
.TP 9m
.BI \&.UR " u"
inicia um hyperlinx para uma URI (URL)
.IR u ;
e termina com o comando
.B UE
correspondente.
Ao se gerar HTML, deve se tornar o comando
\fB<A HREF="\fP\fIu\fP\fB">\fP.
H uma exceo: se 
.I u
tiver o valor ":", no ser gerado nenhum link de hipertexto
at o
.B UE
final. Isto permite desabilitar hyperlinks em frases como
.UR ":"
LALR(1)
.UE
onde os links no so apropriados.
Estas "macros" de hipertexto so novas, e
muitos programas no faro nada com elas. Mas
como muitos programas - inclusive o troff - simplesmente ignoram macros
no definidas (ou na pior das hipteses inclui estas macros como texto),  seguro utiliz-las.
.TP
.BI \&.UE
finaliza o comando
.B UR
correspondente.
Ao gerar HTML, isto deve ser traduzido como
\fB</A>\fP.
.TP
.BI \&.UN " u"
Cria um local de hipertexto chamado
.IR u ;
no  necessrio incluir um
.B UE
correspondente.
Ao gerar HTML, isto deve ser traduzido como
\fB<A NAME="\fP\fIu\fP\fB" id="\fP\fIu\fP\fB">&nbsp;</A>\fP
(O &nbsp;  opcional se no for necessrio suporte ao Mosaic).
.SS "Outras macros"
.TP 9m
.B \&.DT
Reinicializa a indentao com os valroes padro (a cada 0.5 polegada)
sem introduzir uma quebra.
.TP
.BI \&.IX " \&..."
Introduz um ndice (para um sistema de busca ou ndice impresso).
Esta informao normalmente no  exibida na pgina.
 seguida por um nico parmetro, que  acrescentado como um nico termo
apontando para uma dada localizao na pgina.
Se houverem dois parmetros, normalmente est no formato Perl manpage: o
primeiro designa o tipo do nome
(pode ser Nome, Titilo, Cabealho, Subseo ou tem)
e o segundo parmetro indica o nome a ser indexado.
Caso contrrio, est no formato de ndice longo:
cada parmetro d um termo de ndice, termo de ndice subordinado,
termo de ndice subsubordinado e assim por diante at que se encontre um parmetro vazio,
um parmetro com o nome do programa (\eem) e uma descrio breve.
Isto pode ser seguido por outro parmetro vazio e talvez por
mensagens de controle de pgina como 'PAGE START'.
Um exemplo seria:
"programming tools" "make" "" "\efLmake\efP \e(em build programs".
.TP
.BI \&.PD " d"
Ajusta a distncia entre pargrafos para d
(se omitido, d=0.4v).
No introduz quebra.
.TP
.BI \&.SS " t"
Subcabealho
.I t
(mesmo que
.BR \&.SH ,
mas usado para subsees dentro de uma seo.
.SS "Strings pr-definidas"
O pacote
.B man
tem as seguintes strings pr-definidas:
.IP \e*R
Marca registrada: \*R
.IP \e*S
Mudar para tamanho de fonte padro
.IP \e*(Tm
Marca: \*(Tm
.IP \e*(lq
Aspas anguladas (esquerda): \*(lq
.IP \e*(rq
Aspas anguladas (direita): \*(rq
.SH "SUBCONJUNTO SEGURO"
Embora o 
.B man 
seja tecnicamente um pacote de macros troff, muitos programas que processam
pginas de manual no implementam todos os recursos do troff.
Portanto,  melhor evitar os recursos mais exticos para que eles funcionem
corretamente.
Evite os preprocessadores troff.
Se isto for inevitvel, use o
.BR tbl (1),
mas com os comandos
.B IP
e
.B TP
para tabelas de duas colunas.
Evite usar clculos: a maioria dos programas no os entende.
Use comandos simples, fceis de traduzir.
As seguintes macros so consideradas seguras,
embora muitas vezes sejam ignoradas pelos tradutores:
.BR \e" ,
.BR . ,
.BR ad ,
.BR bp ,
.BR br ,
.BR ce ,
.BR de ,
.BR ds ,
.BR el ,
.BR ie ,
.BR if ,
.BR fi ,
.BR ft ,
.BR hy ,
.BR ig ,
.BR in ,
.BR na ,
.BR ne ,
.BR nf ,
.BR nh ,
.BR ps ,
.BR so ,
.BR sp ,
.BR ti ,
.BR tr .
.PP
Pode-se tambm usar as seqncias de escape troff (que comeam
com \e).
Para incluir uma barra invertida como texto,
use \ee.
Outras seqncias (x ou xx so caracteres
e N  um dgito):
.BR \e' ,
.BR \e` ,
.BR \e- ,
.BR \e. ,
.BR \e" ,
.BR \e% ,
.BR \e*x ,
.BR \e*(xx ,
.BR \e(xx ,
.BR \e$N ,
.BR \enx ,
.BR \en(xx ,
.BR \efx ,
e
.BR \ef(xx .
Evite desenhar com as seqncias de escape.
.PP
No use o parmetro opcional de
.B bp
('break page' - quebra de pgina).
Use apenas valores positivos para
.B sp
(espao vertical).
No defina uma macro
.RB ( de )
com o mesmo nome de uma macro deste pacote ou do mdoc que tenha
um significado diferente:  provvel que
estas redefinies sejam ignoradas.
Toda indentao positiva
.RB ( in )
deve ter uma indentao negativa correspondente.
( melhor, no entanto, usar as macros
.B RS
e
.B RE
).
O teste condicional
.RB ( if,ie )
deve ter apenas 't' ou 'n' como condio.
Apenas as tradues do tipo
.RB ( tr )
que puderem ser ignoradas devem ser usadas.
Mudanas de fonte com
.RB ( ft
ou com a seqncia \fB\ef\fP
devem usar apenas os valores 1, 2, 3, 4, R, I, B, P ou CW
(o comando ft tambm pode ser usado sem parmetros).
.PP
Se voc usar recursos que no sejam estes, confira cuidadosamente
os resultados em vrios programas.
Se a seqncia for segura, favor
informar ao mantenedor deste
documento para
que ele o adicione.
.SH OBSERVAES
.PP
Procure incluir as URL ou URIs integrais no prprio texto, porque
alguns programas como
.BR man2html (1)
podem transform-las automaticamente em links.
Voc tambm pode usar a macro
.B UR
para identificar links a informaes relacionadas.
Se voc usar URLs, coloque o endereo inteiro
(ex. <http://www.kernelnotes.org>) para que os programas 
as encontrem automaticamente.
.PP
Programas que processem estes arquivos devem abrir o arquivo e examinar
o primeiro caracter que no seja um espao. Um ponto (.) ou aspa nica (')
no comeo 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. sada de "catman").
.PP
Muitas pginas comeam com '\e" seguido de espao e uma lista de caracteres
que prescrevem um preprocessamento para a pgina.
Para portabilidade com tradutores no troff, recomendamos que no se use nada
alm do
.BR tbl (1),
que o linux detecta automaticamente.
No entanto, voc pode desejar incluir esta informao para que sua pgina
seja manuseada por outros sistemas menos capazes.
Aqui esto as definies dos preprocessadores indicados pelos seguites caracteres:
.TP 3
.B e
eqn(1)
.TP
.B g
grap(1)
.TP
.B p
pic(1)
.TP
.B r
refer(1)
.TP
.B t
tbl(1)
.TP
.B v
vgrind(1)
.SH ARQUIVOS
.I /usr/local/lib/groff/tmac/tmac.an
.br
.I /usr/man/whatis
.SH PROBLEMAS
.PP
A maioria das macros descreve formatao (fontes, espaamentos...) ao invs
de semntica (como: este texto  uma referncia a outra pgina), comparado
com formatos como mdoc e DocBook (ento HTML tem mais marcas
de semntica).
Isto torna mais difcil traduzir ou tornar consistente o formato
.B man
para outros meios,
dificulta ainda a insero de
referncias cruzadas.
Ao se limitar ao subconjuto padro acima, a automatizao da transio para
outro formato de manual no futuro ficar facilitada.
.LP
A macro
.B TX
da Sun no est implementada.
.SH AUTORES
.IP \(em 3m
James Clark (jjc@jclark.com) escreveu a implementao do pacote de macros.
.IP \(em
Rickard E. Faith (faith@cs.unc.edu) escreveu a verso inicial
desta pgina.
.IP \(em
Jens Schweikhardt (schweikh@noc.fdn.de) escreveu o Linux Man-Page Mini-HOWTO
(que influenciou esta pgina de manual).
.IP \(em
David A. Wheeler (dwheeler@ida.org) modificou consideravelmente esta pgina,
adicionando informaes detalhadas sobre sees e macros.
.SH "VEJA TAMBM"
.BR apropos (1),
.BR groff (1),
.BR man (1),
.BR man2html (1),
.BR mdoc (7),
.BR mdoc.samples (7),
.BR whatis (1).
.SH TRADUZIDO POR LDP-BR em 21/08/2000.
\&\fR\&\f(CWPaulo Csar Mendes <drps@ism.com.br> (traduo)\fR
\&\fR\&\f(CWAndr L. Fassone Canova <lonelywolf@blv.com.br> (reviso)\fR