1 This is help2man-es.info.tmp, produced by makeinfo version 6.8 from
4 Este fichero contiene la documentación del programa GNU ‘help2man’, el
5 cual genera páginas de manual básicas a partir de la salida de ‘--help’
6 y ‘--version’ de otros programas.
8 Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2009, 2010,
9 2011, 2012, 2013, 2014, 2015, 2020, 2021 Free Software Foundation, Inc.
11 Está permitido hacer copias exactas de este manual y distribuirlo, a
12 condición de que la nota de copyright y esta nota de permiso se
13 preserven en todas las copias.
15 Está permitido hacer copias y distribuir versiones modificadas de
16 este manual bajo las condiciones para copias exactas, a condición de que
17 el trabajo derivado resultante en su totalidad se distribuya bajo los
18 términos de una nota de permiso indéntica a esta.
20 Está permitido copiar y distribuir traducciones de este manual a otro
21 idioma bajo las condiciones para versiones modificadas descritas
22 anteriormente, salvo esta nota de permiso, que puede estar formulada en
23 una traducción aprobada por la Fundación.
24 INFO-DIR-SECTION Desarrollo de software
26 * help2man-es: (help2man-es). Generación automática de la página del
31 File: help2man-es.info.tmp, Node: Top, Next: Visión de conjunto, Up: (dir)
36 ‘help2man’ genera páginas de manual básicas a partir de la salida de
37 ‘--help’ y ‘--version’ de otros programas.
41 * Visión de conjunto:: Visión de conjunto de ‘help2man’.
42 * Invocar help2man:: Cómo ejecutar ‘help2man’.
43 * recomendaciones para --help:: Formato recomendado para la salida
45 * Incluir texto:: Incluir texto adicional en la salida.
46 * Empleo con Makefile:: Utilizar ‘help2man’ con ‘make’.
47 * Pagínas de manual regionales:: Generar páginas de manual en la
49 * Ejemplo:: Ejemplo de la salida de ‘help2man’.
50 * Contacto:: Informar de errores y enviar
52 * Obtención:: Obtener ‘help2man’.
55 File: help2man-es.info.tmp, Node: Visión de conjunto, Next: Invocar help2man, Prev: Top, Up: Top
57 1 Visión de conjunto de ‘help2man’
58 **********************************
60 ‘help2man’ es una herramienta para generar automáticamente páginas de
61 manual (man) básicas a partir de la salida de un programa.
63 Aunque las páginas de manual son opcionales para los programas de
64 GNU, son necesarias en otros proyectos, como, por ejemplo, Debian (*note
65 (standards)Man Pages::)
67 Este programa está pensado para que los autores de software dispongan
68 de un modo sencillo de incluir una página de manual en su distribución,
69 sin tener que mantener el documento de dicha página por separado.
71 Si las opciones ‘--help’ y ‘--version’ de un programa producen una
72 salida razonablemente estándar, ‘help2man’ es capaz de reorganizarla de
73 forma que se asemeje a una página de manual.
76 File: help2man-es.info.tmp, Node: Invocar help2man, Next: recomendaciones para --help, Prev: Visión de conjunto, Up: Top
78 2 Cómo ejecutar ‘help2man’
79 **************************
81 La sintaxis para ejecutar el programa ‘help2man’ es:
83 help2man [OPCIÓN]... EJECUTABLE
85 ‘help2man’ acepta las siguientes opciones:
89 Utiliza TEXTO como descripción del párrafo ‘NOMBRE’ de la página de
92 Si no se indica otra cosa (a falta de algo mejor), este párrafo
93 contiene ‘página de manual de PROGRAMA VERSIÓN’.
95 Esta opción anula una sección ‘[nombre]’ de fichero de inclusión
96 (*note Incluir texto::).
100 Utiliza SECCIÓN como sección de la página de manual. La sección
105 Establece SECCIÓN como nombre de la sección del manual, que se
106 utilizará como título centrado de la página de manual. ‘Órdenes de
107 usuario’ está predefinida para las páginas de la sección 1,
108 ‘Juegos’ para la sección 6 y ‘Utilidades para la administración del
109 sistema’ para las secciones 8 y 1M.
113 El programa fuente se utiliza como pie de página y suele incluir el
114 nombre de la organización o la «suite» de la que forma parte el
115 programa. El valor predefinido es el nombre del paquete y la
120 Selecciona los parámetros regionales para la salida (predefinido
121 ‘C’). Tanto el programa como ‘help2man’ deben aceptar el LOCALE
122 dado (*note Pagínas de manual regionales::).
126 Incluye contenido procedente de FICHERO (*note Incluir texto::).
129 ‘--opt-include=FICHERO’
130 Variante de ‘--include’ para ser utilizada en reglas de patrones de
131 Makefile que no requieran la existencia de FICHERO.
135 Manda la salida a FICHERO en lugar de a ‘stdout’.
139 Nombre del manual Texinfo.
143 Evita que se incluya un párrafo ‘VÉASE TAMBIÉN’ que dirija al
144 lector a la documentación Texinfo.
148 Elimina el prefijo ‘lt-’ en todos los lugares de la sinopsis en los
149 que aparece el nombre del programa (‘libtool’ crea unos scripts en
150 el directorio de build que invocan ‘foo’ como ‘.libs/lt-foo’).
154 Muestra información de ayuda o sobre la versión.
156 Si no se indica otra cosa, ‘help2man’ pasa al ejecutable las opciones
157 estándares ‘--help’ y ‘--version’, aunque se pueden especificar otras
158 alternativas mediante:
161 ‘--help-option=OPCIÓN’
162 Texto de la opción de ayuda.
165 ‘--version-option=OPCIÓN’
166 Texto de la opción de versión.
168 ‘--version-string=TEXTO’
171 ‘--no-discard-stderr’
172 Incluye stderr cuando se analiza la salida de las opciones.
175 File: help2man-es.info.tmp, Node: recomendaciones para --help, Next: Incluir texto, Prev: Invocar help2man, Up: Top
177 3 Recomendaciones de ‘--help’
178 *****************************
180 He aquí algunas recomendaciones sobre lo que se debe incluir en ‘--help’
181 para obtener el mejor resultado posible de ‘help2man’, una página de
182 manual respetable para beneficio de los usuarios.
184 Véase *note (standards)Command-Line Interfaces:: y *note
185 (standards)Man Pages::, para consultar los estándares oficiales de GNU
186 relacionados con ‘--help’ y con las páginas de manual.
188 • Resumen de los modos de invocar el programa. Si hay distintas
189 maneras de utilizar el programa, cada una con su propio modo de
190 invocarlo, hay que enumerarlos todos. Por ejemplo (editado por
191 razones de brevedad):
193 Modo de empleo: cp [OPCIÓN]... ORIGEN DESTINO
194 o: cp [OPCIÓN]... ORIGEN... DIRECTORIO
197 Utiliza ‘argv[0]’ como nombre del programa en estas sinopsis, tal
198 cual, sin eliminar la información del directorio, lo cual contrasta
199 con el nombre canónico (constante) del programa que se utiliza en
202 • Breve explicación de lo que hace el programa, incluido el
203 comportamiento predeterminado y/o más común. Por ejemplo, este es
206 Copia ORIGEN en DESTINO o varios ORÍGENES en DIRECTORIO.
208 • Lista de opciones sangrada a la columna 2. Si el programa acepta
209 opciones de un solo carácter, se deben poner estas primero,
210 seguidas de la la opción larga equivalente, si la hay. Si una
211 opción toma argumento, hay que incluirlo y hay que ponerle un
212 nombre representativo. Es conveniente alinear verticalmente las
213 descripciones. Nótese que la descripción deben estar separada al
214 menos por dos espacios de las opciones, y las descripciones que
215 continúan en líneas sucesivas deben comenzar en la misma columna.
217 He aquí otro extracto (editado) de ‘cp’ que muestra una opción
218 corta y su equivalente opción larga, una opción solamente larga y
219 una opción solamente corta:
221 -a, --archive igual que -dpR
222 --backup[=CONTROL] hace copia de seguridad de cada ...
223 -b como --backup excepto ...
225 En el caso de programas con muchas opciones, es deseable dividir la
226 lista de opciones en varias secciones, tales como ‘Globales’,
227 ‘Control de la salida’ o aquello que tenga sentido en cada caso
228 concreto. Normalmente es preferible ordenarlas alfabéticamente (en
229 primer lugar por el nombre de la opción corta y luego por el de la
230 larga) dentro de cada sección o la lista completa si no hay
233 • Cualquier otra información adicional sobre el funcionamiento del
234 programa, tal como las variables de entorno que le afectan,
235 explicaciones más detalladas sobre las opciones, etc. Por ejemplo,
236 ‘cp’ explica ‘VERSION_CONTROL’ y los ficheros dispersos.
238 • Algún ejemplo del modo de empleo típico, a su discreción. Es muy
239 recomendable, ya que un buen ejemplo suele servir más que mil
240 palabras de descripción.
242 • Para finalizar, unas palabras sobre cómo informar de errores por
243 correo. Normalmente, MAILING-ADDRESS será ‘bug-PROGRAMA@gnu.org’;
244 utilice esta forma para programas de GNU siempre que sea posible.
245 También es bueno mencionar la página principal del programa, otras
246 listas de correo, etc.
248 Los interfaces de programación ‘argp’ y ‘popt’ permiten especificar
249 las descripciones de opciones de ‘--help’ siguiendo la misma estructura
250 que el resto de deficiones de opciones, por lo que pueden utilizarse
251 estas rutinas en lugar de ‘getopt’ para analizar las opciones, si se
254 ‘help2man’ se sirve de ciertas heurísticas predefinidas para detectar
255 las secciones de la página de manual: una línea constituida por
256 ‘Options:’, por ejemplo, hará que el texto subsiguiente aparezca en la
257 sección ‘OPTIONS’, y una línea que comience por ‘Copyright’ aparecerá en
258 la sección ‘COPYRIGHT’. Al margen de estas heurísticas, una línea
259 constituida por ‘*Words*’ iniciará una nueva sección, y ‘Words:’, una
263 File: help2man-es.info.tmp, Node: Incluir texto, Next: Empleo con Makefile, Prev: recomendaciones para --help, Up: Top
265 4 Incluir texto adicional en la salida
266 **************************************
268 Se puede incluir texto estático adicional en la página de manual
269 generada mediante las opciones ‘--include’ y ‘--opt-include’ (*note
270 Invocar help2man::). Aunque estos ficheros pueden tener cualquier
271 nombre, sugerimos utilizar, por coherencia, la extensión ‘.h2m’ para los
272 ficheros de inclusión de ‘help2man’.
274 El formato de los ficheros que se incluyen mediante estas opciones es
283 Los bloques de texto en formato *roff se insertan en la salida, bien
284 al comienzo de la ‘[sección]’ dada, bien después de un párrafo que
285 coincida con ‘/patrón/’.
287 Los patrones utilizan la sintaxis de expresiones regulares de Perl y
288 pueden ir seguidos de los modificadores ‘i’, ‘s’ o ‘m’ (*note perlre(1):
289 (*manpages*)perlre.).
291 Las líneas anteriores a la primera sección o patrón que comiencen con
292 ‘-’ se procesan como opciones. Todo lo demás se descarta sin avisar y
293 se puede utilizar para comentarios, claves RCS y cosas por el estilo.
295 El orden de salida de las secciones (aquellas que estén includidas)
311 Las secciones ‘[nombre]’ o ‘[sinopsis]’ del fichero de inclusión
312 reemplazan lo que se hubiera generado automáticamente (aunque este
313 comportamiento puede anularse con ‘--name’ si es preciso).
315 Otras secciones se añaden a la salida generada automáticamente para
316 las secciones estándares dadas arriba o se incluyen en _otros_ (ver
317 arriba) en el orden en que se encuentren en el fichero de inclusión.
319 Puede indicarse explícitamente dónde se desea colocar el texto dentro
320 de la sección mediante la sintaxis ‘[<sección]’, ‘[=sección]’ o
321 ‘[>sección]’, para ubicar el texto adicional antes, en lugar de o
322 después de la salida predeterminada, respectivamente.
325 File: help2man-es.info.tmp, Node: Empleo con Makefile, Next: Pagínas de manual regionales, Prev: Incluir texto, Up: Top
327 5 Utilizar ‘help2man’ con ‘make’.
328 *********************************
330 A la hora de utilizar ‘help2man’ en Makefiles se sugiere hacer que la
331 página de manual no dependa del binario sino de los fuentes en los que
332 están definas las salidas de ‘--help’ y ‘--version’.
334 Este modo de empleo hace posible que el mantenedor genere la página
335 de manual y la incluya en la distribución, sin obligar al usuario final
336 a tener ‘help2man’ instalado.
338 Un ejemplo de regla para el programa ‘prog’ podría ser:
340 prog.1: $(srcdir)/main.c
341 -$(HELP2MAN) --output=$@ --name='un programa de ejemplo' ./prog
343 El valor de ‘HELP2MAN’ puede definirse en ‘configure.in’ mediante una
344 de estas instrucciones:
346 AM_MISSING_PROG(HELP2MAN, help2man)
348 para ‘automake’ o algo parecido a esto:
350 AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
352 para ‘autoconf’ solo.
355 File: help2man-es.info.tmp, Node: Pagínas de manual regionales, Next: Ejemplo, Prev: Empleo con Makefile, Up: Top
357 6 Generar páginas de manual en lengua nativa
358 ********************************************
360 Se pueden generar páginas de manual para cualesquier parámetros
361 regionales que sean aceptados tanto por el programa en cuestión como por
362 ‘help2man’ con la opción ‘--locale’ (‘-L’).
364 help2man -L fr_FR@euro -o cp.fr.1 cp
366 Consúltese <http://translationproject.org/domain/help2man.html> para
367 ver los idiomas que ‘help2man’ acepta actualmente, y *note Contacto::
368 para saber cómo enviar otras traducciones.
370 6.1 Configuración de la ubicación de los catálogos de mensajes
371 ==============================================================
373 Cuando se crean páginas de manual regionales a partir del directorio de
374 «build» de un programa, es probable que las traducciones instaladas en
375 la ubicación estándar no sean correctas, si es que están instaladas,
376 para la versión del programa que se está construyendo.
378 ‘help2man’ incluye una biblioteca precargable que intercepta las
379 llamadas ‘bindtextdomain’ que configuran la ubicación de los catálogos
380 de mensajes para el dominio definido en ‘$TEXTDOMAIN’ y la sustituye por
381 la ruta definida en ‘$LOCALEDIR’.
385 mkdir -p tmp/fr/LC_MESSAGES
386 cp po/fr.gmo tmp/fr/LC_MESSAGES/PROG.mo
387 LD_PRELOAD="/usr/lib/help2man/bindtextdomain.so" \
390 help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
393 hará que PROG cargue el catálogo de mensajes de ‘tmp’ en vez de
397 • La generalización de ‘fr_FR@euro’ a ‘fr’ en el ejemplo anterior se
398 lleva a cabo por medio de ‘gettext’. Si hubiera disponible una
399 coincidencia más específica, también se la habría asociado.
401 • La precarga solo se ha probado con ‘eglibc’ 2.11.2 y ‘gettext’
402 0.18.1.1 en un sistema GNU/Linux; estamos interesados en saber si a
403 usted le funciona (*note Contacto::).
406 File: help2man-es.info.tmp, Node: Ejemplo, Next: Contacto, Prev: Pagínas de manual regionales, Up: Top
408 7 Ejemplo de la salida de ‘help2man’
409 ************************************
411 Dado un hipotético programa ‘foo’ que produce la siguiente salida:
416 Copyright (C) 2011 Free Software Foundation, Inc.
417 Esto es software libre; consúltense en los fuentes las condiciones de copia.
418 No hay NINGUNA garantía, tampoco por RAZONES DE COMERCIALIZACIÓN O ADECUACIÓN
419 A UN DETERMINADO FIN EN CONCRETO.
421 Creado por U. Programador.
423 GNU `foo' no hace nada interesante salvo servir de ejemplo a
426 Modo de empleo: foo [OPCIÓN]...
429 -a, --option una opción
430 -b, --another-option[=VALOR]
433 --help muestra esta información de ayuda y termina
434 --version saca la información sobre la versión y termina
438 foo --option exactamente igual con `--option'
440 Informar de errores a <bug-gnu-utils@gnu.org>.
442 ‘help2man’ genera entrada en formato ‘nroff’ para una página de
443 manual que se formateará de forma similar a este ejemplo:
445 FOO(1) Órdenes de usuario FOO(1)
448 foo - página de manual de foo 1.1
454 GNU `foo' no hace nada interesante salvo servir de ejemplo a
461 -b, --another-option[=VALOR]
464 --help muestra esta información de ayuda y termina
467 saca la información sobre la versión y termina
473 exactamente igual con `--option'
476 Creado por U. Programador.
479 Informar de errores a <bug-gnu-utils@gnu.org>.
482 Copyright (C) 2011 Free Software Foundation, Inc.
483 Esto es software libre; consúltense en los fuentes las condiciones de
484 copia. No hay NINGUNA garantía, tampoco por RAZONES DE COMERCIALIZACIÓN
485 O ADECUACIÓN A UN DETERMINADO FIN EN CONCRETO.
488 La documentación completa de foo se mantiene como manual en
489 formato Texinfo. Si los programas info y foo están
490 correctamente instalados en su sistema, la orden
494 debería llevarle al manual completo.
496 foo 1.1 Mayo 2011 FOO(1)
499 File: help2man-es.info.tmp, Node: Contacto, Next: Obtención, Prev: Ejemplo, Up: Top
501 8 Informar de errores o sugerencias
502 ***********************************
504 Si encuentra algún problema o tiene alguna sugerencia en relación con
505 este programa o con este manual, le agradeceríamos que nos lo comunicara
506 a la dirección <bug-help2man@gnu.org>.
508 Nota para traductores: las traducciones se gestionan a través de
509 Translation Project (http://translationproject.org/) consúltese
510 <http://translationproject.org/html/translators.html> para conocer los
514 File: help2man-es.info.tmp, Node: Obtención, Prev: Contacto, Up: Top
519 La última versión de esta distribución está disponible en internet en
522 <http://ftpmirror.gnu.org/help2man/>
524 Si falla la redirección automática, la lista de espejos está en:
526 <http://www.gnu.org/order/ftp.html>
528 O, si hiciera falta, puede usarse el servidor ftp principal de GNU:
529 <http://ftp.gnu.org/gnu/help2man/>
534 Node: Visión de conjunto
\7f2250
535 Node: Invocar help2man
\7f3154
536 Node: recomendaciones para --help
\7f6329
537 Node: Incluir texto
\7f10716
538 Node: Empleo con Makefile
\7f12922
539 Node: Pagínas de manual regionales
\7f13980
540 Node: Ejemplo
\7f16114
541 Node: Contacto
\7f18981
542 Node: Obtención
\7f19549