help2man-pt_BR.info

   1 This is help2man-pt_BR.info.tmp, produced by makeinfo version 6.5 from
   2 help2man-pt_BR.texi.
   3
   4 Esse arquivo documenta o comando GNU ‘help2man’ que produz páginas de
   5 manual simples a partir da saída de ‘--help’ e ‘--version’ de outros
   6 comandos.
   7
   8    Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
   9 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
  10
  11    Está concedida permissão para fazer e distribuir cópias literais
  12 deste manual desde que o aviso de direitos autorais e este aviso de
  13 permissão sejam preservados em todas as cópias.
  14
  15    Está concedida permissão para copiar e distribuir versões modificadas
  16 deste manual nas condições de cópia literal, desde que todo o trabalho
  17 derivado resultante seja distribuído sob os termos de um aviso de
  18 permissão idêntico a este.
  19
  20    Está concedida permissão para copiar e distribuir as traduções deste
  21 manual para outro idioma, nas condições acima para versões modificadas,
  22 exceto que este aviso de permissão pode ser indicado em uma tradução
  23 aprovada pela Foundation.
  24 INFO-DIR-SECTION Desenvolvimento de software
  25 START-INFO-DIR-ENTRY
  26 * help2man-pt_BR: (help2man-pt_BR).  Geração automática de página de
  27                                        manual.
  28 END-INFO-DIR-ENTRY
  29
  30 \1f
  31 File: help2man-pt_BR.info.tmp,  Node: Top,  Next: Visão geral,  Up: (dir)
  32
  33 ‘help2man’
  34 **********
  35
  36 ‘help2man’ produz páginas de manual simples a partir da saída de
  37 ‘--help’ e ‘--version’ de outros comandos.
  38
  39 * Menu:
  40
  41 * Visão geral::             Visão geral do ‘help2man’.
  42 * Chamando help2man::        Como executar o ‘help2man’.
  43 * Recomendações do --help::  Formatação recomendada para a saída
  44                                de‘--help’.
  45 * Incluindo texto::          Incluindo texto adicional na saída.
  46 * Uso de Makefile::          Usando ‘help2man’ com ‘make’.
  47 * Páginas man localizadas::  Produzindo páginas de manual de
  48                                idiomanativo.
  49 * Exemplo::                  Exemplo de saída do ‘help2man’.
  50 * Relatórios::              Relatando erros e sugestões.
  51 * Disponibilidade::          Obtendo o ‘help2man’.
  52
  53 \1f
  54 File: help2man-pt_BR.info.tmp,  Node: Visão geral,  Next: Chamando help2man,  Prev: Top,  Up: Top
  55
  56 1 Visão geral do ‘help2man’
  57 ***************************
  58
  59 ‘help2man’ é uma ferramenta para geração automática de páginas de manual
  60 simples a partir da saída de programa.
  61
  62    Apesar de páginas de manual serem opcionais para programas GNU,
  63 outros projetos, como Debian, as exigem (*note (standards)Man Pages::)
  64
  65    Este programa destina-se a fornecer uma maneira fácil para autores de
  66 software incluir uma página de manual em sua distribuição sem ter que
  67 manter esse documento.
  68
  69    Dado um programa que produz saídas razoavelmente padrão de ‘--help’ e
  70 ‘--version’, o ‘help2man’ pode rearranjar aquela saída para algo que se
  71 parece uma página de manual.
  72
  73 \1f
  74 File: help2man-pt_BR.info.tmp,  Node: Chamando help2man,  Next: Recomendações do --help,  Prev: Visão geral,  Up: Top
  75
  76 2 Como executar o ‘help2man’
  77 ****************************
  78
  79 O formato para executar o programa ‘help2man’ é:
  80
  81      help2man [OPÇÃO]... EXECUTÁVEL
  82
  83    ‘help2man’ oferece suporte às seguintes opções:
  84
  85 ‘-n TEXTO’
  86 ‘--name=TEXTO’
  87      Usa TEXTO como a descrição para o parágrafo ‘NAME’ da página de
  88      manual.
  89
  90      Por padrão (para desejo de algo melhor) esse parágrafo contém
  91      ‘página de manual para PROGRAMA VERSÃO’.
  92
  93      Essa opção sobrescreve um arquivo de inclusão da seção ‘[name]’
  94      (*note Incluindo texto::).
  95
  96 ‘-s SEÇÃO’
  97 ‘--section SEÇÃO’
  98      Usa SEÇÃO como a seção para a página man.  A seção padrão é 1.
  99
 100 ‘-m MANUAL’
 101 ‘--manual=MANUAL’
 102      Define o nome da seção de manual para SEÇÃO, usada como cabeçalho
 103      centralizado para a página e manual.  Por padrão, ‘Comandos de
 104      usuários’ é usada para páginas na seção 1, ‘Jogos’ para a seção 6 e
 105      ‘Utilitários de Administração de Sistema’ para seções 8 e 1M.
 106
 107 ‘-S FONTE’
 108 ‘--source=FONTE’
 109      A fonte do programa é usada como rodapé de página e, muitas vezes,
 110      contém o nome da organização ou um conjunto de quais o programa faz
 111      parte.  Por padrão, o valor é o nome e a versão do pacote.
 112
 113 ‘-L LOCALIDADE’
 114 ‘--locale=LOCALIDADE’
 115      Seleciona a localidade de saída (padrão ‘C’).  O programa e o
 116      ‘help2man’ devem oferecer suporte à LOCALIDADE dada (*note Páginas
 117      man localizadas::).
 118
 119 ‘-i ARQUIVO’
 120 ‘--include=ARQUIVO’
 121      Inclui material do ARQUIVO (*note Incluindo texto::).
 122
 123 ‘-I ARQUIVO’
 124 ‘--opt-include=ARQUIVO’
 125      Uma variante de ‘--include’ para usar nas regras de padrão Makefile
 126      que não exigem ARQUIVO para existir.
 127
 128 ‘-o ARQUIVO’
 129 ‘--output=ARQUIVO’
 130      Envia saída para ARQUIVO em vez do ‘stdout’ (saída padrão).
 131
 132 ‘-p TEXTO’
 133 ‘--info-page=TEXTO’
 134      Nome do manual Texinfo.
 135
 136 ‘-N’
 137 ‘--no-info’
 138      Suprime a inclusão de um parágrafo ‘SEE ALSO’ direcionando o leitor
 139      para a documentação do Texinfo.
 140
 141 ‘-l’
 142 ‘--libtool’
 143      Descara o prefixo ‘lt-’ de instância do nome do programa na sinopse
 144      (‘libtool’ cria scripts no diretório de compilação que chama ‘foo’
 145      como ‘.libs/lt-foo’).
 146
 147 ‘--help’
 148 ‘--version’
 149      Mostra informações sobre ajuda ou versão.
 150
 151    Por padrão, o ‘help2man’ passa as opções padrão ‘--help’ e
 152 ‘--version’ para o executável, apesar de alternativas poderem ser
 153 especificadas usando:
 154
 155 ‘-h OPÇÃO’
 156 ‘--help-option=OPÇÃO’
 157      Texto da opção de ajuda.
 158
 159 ‘-v OPÇÃO’
 160 ‘--version-option=OPÇÃO’
 161      Texto da opção de version.
 162
 163 ‘--version-string=TEXTO’
 164      Texto da versão.
 165
 166 ‘--no-discard-stderr’
 167      Inclui stderr ao analisar a saída de opção.
 168
 169 \1f
 170 File: help2man-pt_BR.info.tmp,  Node: Recomendações do --help,  Next: Incluindo texto,  Prev: Chamando help2man,  Up: Top
 171
 172 3 Recomendações para ‘--help’
 173 *****************************
 174
 175 Aqui estão algumas recomendações para o que incluir na saída de seu
 176 ‘--help’.  Incluir tais recomendações fornece ao ‘help2man’ a melhor
 177 chance de geração de uma página man respeitável, assim como de
 178 beneficiar usuários diretamente.
 179
 180    Veja *note (standards)Command-Line Interfaces:: e *note
 181 (standards)Man Pages::, para os padrões oficiais do GNU relacionados a
 182 ‘--help’ e páginas man.
 183
 184    • Uma sinopse de como chamar o programa.  Se usos diferentes do
 185      programa possuem chamadas diferentes, então lista todos eles.  Por
 186      exemplo (editado para brevidade):
 187
 188           Usage: cp [OPTION]... SOURCE DEST
 189             or:  cp [OPTION]... SOURCE... DIRECTORY
 190           ...
 191
 192           ou, em português:
 193
 194           Uso: cp [OPÇÃO]... ORIGEM DESTINO
 195            ou: cp [OPÇÃO]... ORIGEM... DIRETÓRIO
 196           ...
 197
 198      Use ‘argv[0]’ para o nome do programa nestas sinopses, exatamente
 199      como está, sem remoção de diretório.  Isso contrasta com o nome
 200      canônico (constante) do programa que é usado em ‘--version’.
 201
 202    • Uma explicação muito breve do que o programa faz, incluindo o
 203      padrão e/ou comportamento típico.  Por exemplo, aqui está a do
 204      ‘cp’:
 205
 206           Copia ORIGEM para DESTINO, ou múltiplas ORIGENs para DIRETÓRIO.
 207
 208    • Uma lista de opções, recuada para a coluna 2.  Se o programa
 209      oferecer suporte às opções de um caractere, coloque-os primeiro e,
 210      em seguida, a opção longa equivalente (se houver).  Se a opção
 211      aceitar um argumento, inclua-o também, dando-lhe um nome
 212      significativo.  Alinhe as descrições em uma coluna conveniente, se
 213      desejar.  Note que, para ser reconhecido corretamente pelo
 214      ‘help2man’, a descrição deve ser separada das opções em pelo menos
 215      dois espaços e as descrições continuadas em linhas subsequentes
 216      devem começar na mesma coluna.
 217
 218      Aqui novamente está um trecho (editado) de ‘cp’, mostrando uma
 219      opção curta com uma opção longa equivalente, uma opção longa apenas
 220      e uma opção curta apenas:
 221
 222             -a, --archive                same as -dpR
 223                 --backup[=CONTROL]       make a backup of each ...
 224             -b                           like --backup but ...
 225
 226           ou, em português:
 227
 228             -a, --archive                o mesmo que -dpR
 229                 --backup[=CONTROLE]      faz uma cópia de segurança de cada ...
 230             -b                           como --backup, mas ...
 231
 232      Para programas que levam muitas opções, pode ser desejável dividir
 233      a lista de opções em seções como ‘Global’, ‘Controle de saída’ ou o
 234      que faz sentido no caso particular.  Geralmente, é melhor
 235      alfabetizar (pelo nome da opção curta primeiro, depois longo)
 236      dentro de cada seção, ou toda a lista se não houver seções.
 237
 238    • Qualquer informação adicional útil sobre o comportamento do
 239      programa, tal como variáveis de ambiente influenciais, mais
 240      explicações de opções, etc.  Por exemplo, ‘cp’ discute
 241      ‘VERSION_CONTROL’ e arquivos esparsos.
 242
 243    • Alguns poucos exemplos de uso típico, a seu critério.  Um bom
 244      exemplo geralmente vale mais do que mil palavras de descrição, por
 245      isso é altamente recomendado.
 246
 247    • No encerramento, uma linha informando como enviar e-mails de
 248      relatórios de erros.  Normalmente, MAILING-ADDRESS será
 249      ‘bug-PROGRAMA@gnu.org’; use esse formulário para programas GNU
 250      sempre que possível.  Também é bom mencionar a página inicial do
 251      programa, outras listas de discussão, etc.
 252
 253    As interfaces de programação ‘argp’ e ‘popt’ permitem especificar
 254 descrições de opções para ‘--help’ na mesma estrutura que o resto da
 255 definição da opção; você pode considerar usar essas rotinas para a
 256 análise de opções em vez de ‘getopt’.
 257
 258    Por padrão, ‘help2man’ possui algumas heurísticas para identificar
 259 seções de página manuais: uma linha que consiste em ‘Options:’, por
 260 exemplo, fará com que o texto a seguir apareça na seção ‘OPTIONS’ e uma
 261 linha que comece com ‘Copyright’ aparecerá na seção ‘COPYRIGHT’.  Fora
 262 dessas heurísticas, uma linha que consiste em ‘*Palavras*’ iniciará uma
 263 nova seção, e ‘Palavras:’ uma nova subseção.
 264
 265 \1f
 266 File: help2man-pt_BR.info.tmp,  Node: Incluindo texto,  Next: Uso de Makefile,  Prev: Recomendações do --help,  Up: Top
 267
 268 4 Incluindo texto adicional na saída
 269 ************************************
 270
 271 Texto de estatística adicional pode ser incluído na página de manual
 272 gerada usando as opções ‘--include’ e ‘--opt-include’ (*note Chamando
 273 help2man::).  Enquanto esses arquivos podem ter qualquer nome,
 274 sugerimos, visando consistência, usar a extensão ‘.h2m’ para arquivos de
 275 inclusão do ‘help2man’.
 276
 277    O formato para arquivos incluídos com essas opções é simples:
 278
 279      [section]
 280      texto
 281
 282      /padrão/
 283      texto
 284
 285    Blocos de texto literal *roff são inseridos na saída ou no início de
 286 uma dada ‘[section]’ (não diferencia maiúsculo/minúsculo), ou após um
 287 parágrafo que coincida com um parágrafo correspondendo a ‘/padrão/’.
 288
 289    Os padrões usam a sintaxe da expressão regular Perl e podem ser
 290 seguidos pelos modificadores ‘i’, ‘s’ ou ‘m’ (*note perlre(1):
 291 (*manpages*)perlre.)
 292
 293    As linhas antes da primeira seção ou de um padrão que comece com ‘-’
 294 são processadas como opções.  Qualquer outra coisa é silenciosamente
 295 ignorada e pode ser usada para comentários, palavras-chaves RCS e coisas
 296 do tipo.
 297
 298    A ordem da saída das seções é:
 299
 300      NOME
 301      SINOPSE
 302      DESCRIÇÃO
 303      OPÇÕES
 304      _outra_
 305      AMBIENTE
 306      ARQUIVOS
 307      EXEMPLOS
 308      AUTOR
 309      RELATANDO ERROS
 310      DIREITOS AUTORAIS
 311      VEJA TAMBÉM
 312
 313    Todas as seções ‘[name]’ ou ‘[synopsis]’ que aparecerem no arquivo de
 314 inclusão substituirão o que teria sido produzido automaticamente (embora
 315 você ainda possa substituir o anterior com ‘--name’, se necessário).
 316
 317    Outras seções são acrescentadas antes da saída produzida
 318 automaticamente para as seções padrões citadas acima ou inclusas na
 319 posição _outra_ (acima) na ordem em que elas forem encontradas no
 320 arquivo de inclusão.
 321
 322    A colocação do texto dentro da seção pode ser explicitamente
 323 solicitada usando a sintaxe ‘[<section]’, ‘[=section]’ ou ‘[>section]’
 324 para colocar o texto adicional antes, no lugar de, ou após a saída
 325 padrão, respectivamente.
 326
 327 \1f
 328 File: help2man-pt_BR.info.tmp,  Node: Uso de Makefile,  Next: Páginas man localizadas,  Prev: Incluindo texto,  Up: Top
 329
 330 5 Usando ‘help2man’ com ‘make’
 331 ******************************
 332
 333 Um uso sugerido do ‘help2man’ em Makefiles é que a página do manual
 334 dependa não do binário, mas do(s) arquivo(s) fonte nos quais a saída de
 335 ‘--help’ e ‘--version’ estão definidas.
 336
 337    Este uso permite que uma página de manual seja gerada pelo mantenedor
 338 e incluída na distribuição, sem exigir que o usuário final tenha o
 339 ‘help2man’ instalado.
 340
 341    Um exemplo de regra para o programa ‘prog’ poderia ser:
 342
 343      prog.1: $(srcdir)/main.c
 344              -$(HELP2MAN) --output=$@ --name='um exemplo de programa' ./prog
 345
 346    O valor de ‘HELP2MAN’ pode ser definido em ‘configure.in’ usando um
 347 dentre:
 348
 349      AM_MISSING_PROG(HELP2MAN, help2man)
 350
 351    para ‘automake’ ou algo como:
 352
 353      AC_PATH_PROG(HELP2MAN, help2man, false // Sem help2man //)
 354
 355    para ‘autoconf’ sozinho.
 356
 357 \1f
 358 File: help2man-pt_BR.info.tmp,  Node: Páginas man localizadas,  Next: Exemplo,  Prev: Uso de Makefile,  Up: Top
 359
 360 6 Produzindo páginas de manual de idioma nativo
 361 ***********************************************
 362
 363 As páginas de manual podem ser produzidas para qualquer localidade que
 364 tem suporte no programa e no ‘help2man’ com a opção ‘--locale’ (‘-L’).
 365
 366      help2man -L fr_FR@euro -o cp.fr.1 cp
 367
 368    Veja <http://translationproject.org/domain/help2man.html> para
 369 relação de suporte a idiomas pelo ‘help2man’ e *note Relatórios:: para
 370 como enviar outras traduções.
 371
 372 6.1 Alterando a localização dos catálogos de mensagens
 373 ======================================================
 374
 375 Ao criar páginas de manual localizadas a partir do diretório de
 376 compilação de um programa, é provável que as traduções instaladas no
 377 local padrão não sejam (se instaladas) corretas para a versão do
 378 programa que está sendo construído.
 379
 380    Uma biblioteca pré-carregável é fornecida com ‘help2man’ que irá
 381 interceptar as chamadas de ‘bindtextdomain’ configurando o local dos
 382 catálogos de mensagens para o domínio fornecido por ‘$TEXTDOMAIN’ e
 383 substituir o local pelo caminho fornecido por ‘$LOCALEDIR’.
 384
 385    Então, por exemplo:
 386
 387      mkdir -p tmp/fr/LC_MESSAGES
 388      cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
 389      LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
 390        LOCALEDIR=tmp \
 391        TEXTDOMAIN=PROG \
 392        help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
 393      rm -rf tmp
 394
 395    fará com que PROG carregue o catálogo de mensagem de ‘tmp’ em vez de
 396 ‘/usr/share/locale’.
 397
 398    Notas:
 399    • A generalização do ‘fr_FR@euro’ para ‘fr’ no exemplo acima é feita
 400      por ‘gettext’, se uma correspondência mais específica estiver
 401      disponível, ela também teria sido re-mapeada.
 402
 403    • Este pré-carregamento só foi testado com ‘eglibc’ 2.11.2 e
 404      ‘gettext’ 0.18.1.1 em um sistema GNU/Linux; deixe-me saber se ele
 405      funciona (ou não) para você (*note Relatórios::).
 406
 407 \1f
 408 File: help2man-pt_BR.info.tmp,  Node: Exemplo,  Next: Relatórios,  Prev: Páginas man localizadas,  Up: Top
 409
 410 7 Exemplo de saída do ‘help2man’
 411 ********************************
 412
 413 Dado um programa hipotético ‘foo’ que produz a seguinte saída:
 414
 415      $ foo --version
 416      GNU foo 1.1
 417
 418      Copyright (C) 2011 Free Software Foundation, Inc.
 419      Este é um software livre; leia os fontes para condições de cópia. NÃO
 420      HÁ QUALQUER GARANTIA; nem para COMERCIALIZAÇÃO ou ADEQUAÇÃO A QUALQUER
 421      PROPÓSITO EM PARTICULAR.
 422
 423      Escrito por O. Programador.
 424      $ foo --help
 425      GNU "foo" faz nada de interessante, exceto servir de exemplo
 426      para o "help2man".
 427
 428      Uso: foo [OPÇÃO]...
 429
 430      Opções:
 431        -a, --option      uma opção
 432        -b, --another-option[=VALOR]
 433                          outra opção
 434
 435            --help        exibe esta ajuda e sai
 436            --version     mostra informações da versão e sai
 437
 438      Exemplos:
 439        foo               faz nada
 440        foo --option      a mesma coisa, com "--option"
 441
 442      Relate erros para <bug-gnu-utils@gnu.org>.
 443
 444    ‘help2man’ vai produzir uma entrada ‘nroff’ para uma página de manual
 445 que será formatada em algo como:
 446
 447      FOO(1)                         Comandos de Usuário                  FOO(1)
 448
 449      NAME
 450             foo - página de manual para 1.1
 451
 452      SYNOPSIS
 453             foo [OPÇÃO]...
 454
 455      DESCRIPTION
 456             GNU "foo" faz nada de interessante, exceto servir como exemplo
 457             para o `help2man'.
 458
 459      OPTIONS
 460             -a, --option
 461                    uma opção
 462
 463             -b, --another-option[=VALOR]
 464                    outra opção
 465
 466             --help exibe essa ajuda e sai
 467
 468             --version
 469                    emite informações da versão e sai
 470
 471      EXAMPLES
 472             foo    faz nada
 473
 474             foo --option
 475                    a mesma coisa, com `--option'
 476
 477      AUTHOR
 478             Escrito por O. Programador.
 479
 480      REPORTING BUGS
 481             Relate erros para <bug-gnu-utils@gnu.org>.
 482
 483      COPYRIGHT
 484             Copyright © 2011 Free Software Foundation, Inc.
 485             Este é um software livre; leia os fontes para condições de cópia.
 486             NÃO HÁ QUALQUER GARANTIA; nem para COMERCIALIZAÇÃO ou ADEQUAÇÃO A
 487             QUALQUER PROPÓSITO EM PARTICULAR.
 488
 489      SEE ALSO
 490             A documentação completa de foo é mantida como um manual em Texinfo.
 491             Se programas  info e foo forem instalados adequadamente,
 492             o comando
 493
 494                    info foo
 495
 496             deve lhe fornecer acesso ao manual completo.
 497
 498      foo 1.1                          Maio de 2011                       FOO(1)
 499
 500 \1f
 501 File: help2man-pt_BR.info.tmp,  Node: Relatórios,  Next: Disponibilidade,  Prev: Exemplo,  Up: Top
 502
 503 8 Reportando erros ou sugestões
 504 *******************************
 505
 506 Se você encontrar problemas ou tiver sugestões sobre este programa ou
 507 manual, informe-os para <bug-help2man@gnu.org>.
 508
 509    Nota para tradutores: Traduções são tratadas por meio do Translation
 510 Project (http://translationproject.org/) veja
 511 <http://translationproject.org/html/translators.html> para detalhes.
 512
 513 \1f
 514 File: help2man-pt_BR.info.tmp,  Node: Disponibilidade,  Prev: Relatórios,  Up: Top
 515
 516 9 Obtendo ‘help2man’
 517 ********************
 518
 519 A versão mais recente desta distribuição está disponível on-line a
 520 partir de espelhos GNU:
 521
 522      <http://ftpmirror.gnu.org/help2man/>
 523
 524    Se o redirecionamento automático falhar, a lista de espelhos está em:
 525
 526      <http://www.gnu.org/order/ftp.html>
 527
 528    Ou, se necessário, você pode usar o servidor GNU ftp principal:
 529      <http://ftp.gnu.org/gnu/help2man/>
 530
 531 \1f
 532 Tag Table:
 533 Node: Top\7f1234
 534 Node: Visão geral\7f2137
 535 Node: Chamando help2man\7f2926
 536 Node: Recomendações do --help\7f5925
 537 Node: Incluindo texto\7f10486
 538 Node: Uso de Makefile\7f12696
 539 Node: Páginas man localizadas\7f13700
 540 Node: Exemplo\7f15761
 541 Node: Relatórios\7f18452
 542 Node: Disponibilidade\7f18933
 543 \1f
 544 End Tag Table
 545
 546 \1f
 547 Local Variables:
 548 coding: utf-8
 549 End: