1 This is help2man-pt_BR.info.tmp, produced by makeinfo version 6.6 from
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
8 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
9 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
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.
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.
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
26 * help2man-pt_BR: (help2man-pt_BR). Geração automática de página de
31 File: help2man-pt_BR.info.tmp, Node: Top, Next: Visão geral, Up: (dir)
36 ‘help2man’ produz páginas de manual simples a partir da saída de
37 ‘--help’ e ‘--version’ de outros comandos.
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
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
49 * Exemplo:: Exemplo de saída do ‘help2man’.
50 * Relatórios:: Relatando erros e sugestões.
51 * Disponibilidade:: Obtendo o ‘help2man’.
54 File: help2man-pt_BR.info.tmp, Node: Visão geral, Next: Chamando help2man, Prev: Top, Up: Top
56 1, Visão geral do ‘help2man’
57 ****************************
59 ‘help2man’ é uma ferramenta para geração automática de páginas de manual
60 simples a partir da saída de programa.
62 Apesar de páginas de manual serem opcionais para programas GNU,
63 outros projetos, como Debian, as exigem (*note (standards)Man Pages::)
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.
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.
74 File: help2man-pt_BR.info.tmp, Node: Chamando help2man, Next: Recomendações do --help, Prev: Visão geral, Up: Top
76 2, Como executar o ‘help2man’
77 *****************************
79 O formato para executar o programa ‘help2man’ é:
81 help2man [OPÇÃO]... EXECUTÁVEL
83 ‘help2man’ oferece suporte às seguintes opções:
87 Usa TEXTO como a descrição para o parágrafo ‘NAME’ da página de
90 Por padrão (para desejo de algo melhor) esse parágrafo contém
91 ‘página de manual para PROGRAMA VERSÃO’.
93 Essa opção sobrescreve um arquivo de inclusão da seção ‘[name]’
94 (*note Incluindo texto::).
98 Usa SEÇÃO como a seção para a página man. A seção padrão é 1.
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.
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.
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
121 Inclui material do ARQUIVO (*note Incluindo texto::).
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.
130 Envia saída para ARQUIVO em vez do ‘stdout’ (saída padrão).
134 Nome do manual Texinfo.
138 Suprime a inclusão de um parágrafo ‘SEE ALSO’ direcionando o leitor
139 para a documentação do Texinfo.
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’).
149 Mostra informações sobre ajuda ou versão.
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:
156 ‘--help-option=OPÇÃO’
157 Texto da opção de ajuda.
160 ‘--version-option=OPÇÃO’
161 Texto da opção de version.
163 ‘--version-string=TEXTO’
166 ‘--no-discard-stderr’
167 Inclui stderr ao analisar a saída de opção.
170 File: help2man-pt_BR.info.tmp, Node: Recomendações do --help, Next: Incluindo texto, Prev: Chamando help2man, Up: Top
172 3, Recomendações para ‘--help’
173 ******************************
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.
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.
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):
188 Usage: cp [OPTION]... SOURCE DEST
189 or: cp [OPTION]... SOURCE... DIRECTORY
194 Uso: cp [OPÇÃO]... ORIGEM DESTINO
195 ou: cp [OPÇÃO]... ORIGEM... DIRETÓRIO
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’.
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
206 Copia ORIGEM para DESTINO, ou múltiplas ORIGENs para DIRETÓRIO.
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.
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:
222 -a, --archive same as -dpR
223 --backup[=CONTROL] make a backup of each ...
224 -b like --backup but ...
228 -a, --archive o mesmo que -dpR
229 --backup[=CONTROLE] faz uma cópia de segurança de cada ...
230 -b como --backup, mas ...
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.
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.
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.
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.
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’.
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.
266 File: help2man-pt_BR.info.tmp, Node: Incluindo texto, Next: Uso de Makefile, Prev: Recomendações do --help, Up: Top
268 4, Incluindo texto adicional na saída
269 *************************************
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’.
277 O formato para arquivos incluídos com essas opções é simples:
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/’.
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):
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
298 A ordem da saída das seções é:
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).
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
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.
328 File: help2man-pt_BR.info.tmp, Node: Uso de Makefile, Next: Páginas man localizadas, Prev: Incluindo texto, Up: Top
330 5, Usando ‘help2man’ com ‘make’
331 *******************************
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.
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.
341 Um exemplo de regra para o programa ‘prog’ poderia ser:
343 prog.1: $(srcdir)/main.c
344 -$(HELP2MAN) --output=$@ --name='um exemplo de programa' ./prog
346 O valor de ‘HELP2MAN’ pode ser definido em ‘configure.in’ usando um
349 AM_MISSING_PROG(HELP2MAN, help2man)
351 para ‘automake’ ou algo como:
353 AC_PATH_PROG(HELP2MAN, help2man, false // Sem help2man //)
355 para ‘autoconf’ sozinho.
358 File: help2man-pt_BR.info.tmp, Node: Páginas man localizadas, Next: Exemplo, Prev: Uso de Makefile, Up: Top
360 6, Produzindo páginas de manual de idioma nativo
361 ************************************************
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’).
366 help2man -L fr_FR@euro -o cp.fr.1 cp
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.
372 6.1, Alterando a localização dos catálogos de mensagens
373 =======================================================
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.
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’.
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" \
392 help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
395 fará com que PROG carregue o catálogo de mensagem de ‘tmp’ em vez de
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.
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::).
408 File: help2man-pt_BR.info.tmp, Node: Exemplo, Next: Relatórios, Prev: Páginas man localizadas, Up: Top
410 7, Exemplo de saída do ‘help2man’
411 *********************************
413 Dado um programa hipotético ‘foo’ que produz a seguinte saída:
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.
423 Escrito por O. Programador.
425 GNU "foo" faz nada de interessante, exceto servir de exemplo
431 -a, --option uma opção
432 -b, --another-option[=VALOR]
435 --help exibe esta ajuda e sai
436 --version mostra informações da versão e sai
440 foo --option a mesma coisa, com "--option"
442 Relate erros para <bug-gnu-utils@gnu.org>.
444 ‘help2man’ vai produzir uma entrada ‘nroff’ para uma página de manual
445 que será formatada em algo como:
447 FOO(1) Comandos de Usuário FOO(1)
450 foo - página de manual para 1.1
456 GNU "foo" faz nada de interessante, exceto servir como exemplo
463 -b, --another-option[=VALOR]
466 --help exibe essa ajuda e sai
469 emite informações da versão e sai
475 a mesma coisa, com `--option'
478 Escrito por O. Programador.
481 Relate erros para <bug-gnu-utils@gnu.org>.
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.
490 A documentação completa de foo é mantida como um manual em Texinfo.
491 Se programas info e foo forem instalados adequadamente,
496 deve lhe fornecer acesso ao manual completo.
498 foo 1.1 Maio de 2011 FOO(1)
501 File: help2man-pt_BR.info.tmp, Node: Relatórios, Next: Disponibilidade, Prev: Exemplo, Up: Top
503 8, Reportando erros ou sugestões
504 ********************************
506 Se você encontrar problemas ou tiver sugestões sobre este programa ou
507 manual, informe-os para <bug-help2man@gnu.org>.
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.
514 File: help2man-pt_BR.info.tmp, Node: Disponibilidade, Prev: Relatórios, Up: Top
516 9, Obtendo ‘help2man’
517 *********************
519 A versão mais recente desta distribuição está disponível on-line a
520 partir de espelhos GNU:
522 <http://ftpmirror.gnu.org/help2man/>
524 Se o redirecionamento automático falhar, a lista de espelhos está em:
526 <http://www.gnu.org/order/ftp.html>
528 Ou, se necessário, você pode usar o servidor GNU ftp principal:
529 <http://ftp.gnu.org/gnu/help2man/>
534 Node: Visão geral
\7f2137
535 Node: Chamando help2man
\7f2928
536 Node: Recomendações do --help
\7f5929
537 Node: Incluindo texto
\7f10492
538 Node: Uso de Makefile
\7f12704
539 Node: Páginas man localizadas
\7f13710
540 Node: Exemplo
\7f15775
541 Node: Relatórios
\7f18468
542 Node: Disponibilidade
\7f18951