Provided by: manpages-pt_20040726-2_all bug

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">&nbsp;</A>  (O  &nbsp;  é
                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)