help2man-es.info

   1 This is help2man-es.info.tmp, produced by makeinfo version 6.5 from
   2 help2man-es.texi.
   3
   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.
   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á 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.
  14
  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.
  19
  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
  25 START-INFO-DIR-ENTRY
  26 * help2man-es: (help2man-es).  Generación automática de la página del
  27                                  manual.
  28 END-INFO-DIR-ENTRY
  29
  30 \1f
  31 File: help2man-es.info.tmp,  Node: Top,  Next: Visión de conjunto,  Up: (dir)
  32
  33 ‘help2man’
  34 **********
  35
  36 ‘help2man’ genera páginas de manual básicas a partir de la salida de
  37 ‘--help’ y ‘--version’ de otros programas.
  38
  39 * Menu:
  40
  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
  44                                     de–help.
  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
  48                                     lenguanativa.
  49 * Ejemplo::                       Ejemplo de la salida de ‘help2man’.
  50 * Contacto::                      Informar de errores y enviar
  51                                     sugerencias.
  52 * Obtención::                    Obtener ‘help2man’.
  53
  54 \1f
  55 File: help2man-es.info.tmp,  Node: Visión de conjunto,  Next: Invocar help2man,  Prev: Top,  Up: Top
  56
  57 1 Visión de conjunto de ‘help2man’
  58 **********************************
  59
  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.
  62
  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::)
  66
  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.
  70
  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.
  74
  75 \1f
  76 File: help2man-es.info.tmp,  Node: Invocar help2man,  Next: recomendaciones para --help,  Prev: Visión de conjunto,  Up: Top
  77
  78 2 Cómo ejecutar ‘help2man’
  79 **************************
  80
  81 La sintaxis para ejecutar el programa ‘help2man’ es:
  82
  83      help2man [OPCIÓN]... EJECUTABLE
  84
  85    ‘help2man’ acepta las siguientes opciones:
  86
  87 ‘-n TEXTO’
  88 ‘--name=TEXTO’
  89      Utiliza TEXTO como descripción del párrafo ‘NOMBRE’ de la página de
  90      manual.
  91
  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’.
  94
  95      Esta opción anula una sección ‘[nombre]’ de fichero de inclusión
  96      (*note Incluir texto::).
  97
  98 ‘-s SECCIÓN’
  99 ‘--section SECCIÓN’
 100      Utiliza SECCIÓN como sección de la página de manual.  La sección
 101      predefinida es 1.
 102
 103 ‘-m MANUAL’
 104 ‘--manual=MANUAL’
 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.
 110
 111 ‘-S SOURCE’
 112 ‘--source=SOURCE’
 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
 116      versión.
 117
 118 ‘-L LOCALE’
 119 ‘--locale=LOCALE’
 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::).
 123
 124 ‘-i FICHERO’
 125 ‘--include=FICHERO’
 126      Incluye contenido procedente de FICHERO (*note Incluir texto::).
 127
 128 ‘-I FICHERO’
 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.
 132
 133 ‘-o FICHERO’
 134 ‘--output=FICHERO’
 135      Manda la salida a FICHERO en lugar de a ‘stdout’.
 136
 137 ‘-p TEXTO’
 138 ‘--info-page=TEXTO’
 139      Nombre del manual Texinfo.
 140
 141 ‘-N’
 142 ‘--no-info’
 143      Evita que se incluya un párrafo ‘VÉASE TAMBIÉN’ que dirija al
 144      lector a la documentación Texinfo.
 145
 146 ‘-l’
 147 ‘--libtool’
 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’).
 151
 152 ‘--help’
 153 ‘--version’
 154      Muestra información de ayuda o sobre la versión.
 155
 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:
 159
 160 ‘-h OPCIÓN’
 161 ‘--help-option=OPCIÓN’
 162      Texto de la opción de ayuda.
 163
 164 ‘-v OPCIÓN’
 165 ‘--version-option=OPCIÓN’
 166      Texto de la opción de versión.
 167
 168 ‘--version-string=TEXTO’
 169      Texto de versión.
 170
 171 ‘--no-discard-stderr’
 172      Incluye stderr cuando se analiza la salida de las opciones.
 173
 174 \1f
 175 File: help2man-es.info.tmp,  Node: recomendaciones para --help,  Next: Incluir texto,  Prev: Invocar help2man,  Up: Top
 176
 177 3 Recomendaciones de ‘--help’
 178 *****************************
 179
 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.
 183
 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.
 187
 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):
 192
 193           Modo de empleo: cp [OPCIÓN]... ORIGEN DESTINO
 194                       o:  cp [OPCIÓN]... ORIGEN... DIRECTORIO
 195           ...
 196
 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
 200      ‘--version’.
 201
 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
 204      el de ‘cp’:
 205
 206           Copia ORIGEN en DESTINO o varios ORÍGENES en DIRECTORIO.
 207
 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.
 216
 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:
 220
 221             -a, --archive                igual que -dpR
 222                 --backup[=CONTROL]       hace copia de seguridad de cada ...
 223             -b                           como --backup excepto ...
 224
 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
 231      secciones.
 232
 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.
 237
 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.
 241
 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.
 247
 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
 252 prefiere.
 253
 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
 260 subsección.
 261
 262 \1f
 263 File: help2man-es.info.tmp,  Node: Incluir texto,  Next: Empleo con Makefile,  Prev: recomendaciones para --help,  Up: Top
 264
 265 4 Incluir texto adicional en la salida
 266 **************************************
 267
 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’.
 273
 274    El formato de los ficheros que se incluyen mediante estas opciones es
 275 muy sencillo:
 276
 277      [sección]
 278      texto
 279
 280      /patrón/
 281      texto
 282
 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/’.
 286
 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.).
 290
 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.
 294
 295    El orden de salida de las secciones (aquellas que estén includidas)
 296 es:
 297
 298      NAME
 299      SYNOPSIS
 300      DESCRIPTION
 301      OPTIONS
 302      _otros_
 303      ENVIRONMENT
 304      FILES
 305      EXAMPLES
 306      AUTHOR
 307      REPORTING BUGS
 308      COPYRIGHT
 309      SEE ALSO
 310
 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).
 314
 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.
 318
 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.
 323
 324 \1f
 325 File: help2man-es.info.tmp,  Node: Empleo con Makefile,  Next: Pagínas de manual regionales,  Prev: Incluir texto,  Up: Top
 326
 327 5 Utilizar ‘help2man’ con ‘make’.
 328 *********************************
 329
 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’.
 333
 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.
 337
 338    Un ejemplo de regla para el programa ‘prog’ podría ser:
 339
 340      prog.1: $(srcdir)/main.c
 341              -$(HELP2MAN) --output=$@ --name='un programa de ejemplo' ./prog
 342
 343    El valor de ‘HELP2MAN’ puede definirse en ‘configure.in’ mediante una
 344 de estas instrucciones:
 345
 346      AM_MISSING_PROG(HELP2MAN, help2man)
 347
 348    para ‘automake’ o algo parecido a esto:
 349
 350      AC_PATH_PROG(HELP2MAN, help2man, false // No help2man //)
 351
 352    para ‘autoconf’ solo.
 353
 354 \1f
 355 File: help2man-es.info.tmp,  Node: Pagínas de manual regionales,  Next: Ejemplo,  Prev: Empleo con Makefile,  Up: Top
 356
 357 6 Generar páginas de manual en lengua nativa
 358 ********************************************
 359
 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’).
 363
 364      help2man -L fr_FR@euro -o cp.fr.1 cp
 365
 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.
 369
 370 6.1 Configuración de la ubicación de los catálogos de mensajes
 371 ==============================================================
 372
 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.
 377
 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’.
 382
 383    Así, por ejemplo:
 384
 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" \
 388        LOCALEDIR=tmp \
 389        TEXTDOMAIN=PROG \
 390        help2man -L fr_FR@euro -i PROG.fr.h2m -o PROG.fr.1 PROG
 391      rm -rf tmp
 392
 393    hará que PROG cargue el catálogo de mensajes de ‘tmp’ en vez de
 394 ‘/usr/share/locale’.
 395
 396    Notas:
 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.
 400
 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::).
 404
 405 \1f
 406 File: help2man-es.info.tmp,  Node: Ejemplo,  Next: Contacto,  Prev: Pagínas de manual regionales,  Up: Top
 407
 408 7 Ejemplo de la salida de ‘help2man’
 409 ************************************
 410
 411 Dado un hipotético programa ‘foo’ que produce la siguiente salida:
 412
 413      $ foo --version
 414      GNU foo 1.1
 415
 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.
 420
 421      Creado por U. Programador.
 422      $ foo --help
 423      GNU `foo' no hace nada interesante salvo servir de ejemplo a
 424      `help2man'.
 425
 426      Modo de empleo: foo [OPCIÓN]...
 427
 428      Options:
 429        -a, --option      una opción
 430        -b, --another-option[=VALOR]
 431                          otra opción
 432
 433            --help        muestra esta información de ayuda y termina
 434            --version     saca la información sobre la versión y termina
 435
 436      Ejemplos:
 437        foo               no hace nada
 438        foo --option      exactamente igual con `--option'
 439
 440      Informar de errores a <bug-gnu-utils@gnu.org>.
 441
 442    ‘help2man’ genera entrada en formato ‘nroff’ para una página de
 443 manual que se formateará de forma similar a este ejemplo:
 444
 445      FOO(1)                       Órdenes de usuario                     FOO(1)
 446
 447      NOMBRE
 448             foo - página de manual de foo 1.1
 449
 450      SINOPSIS
 451             foo [OPCIÓN]...
 452
 453      DESCRIPCIÓN
 454             GNU  `foo'  no hace nada interesante salvo servir de ejemplo a
 455             `help2man'.
 456
 457      OPCIONES
 458             -a, --option
 459                    una opción
 460
 461             -b, --another-option[=VALOR]
 462                    otra opción
 463
 464             --help muestra esta información de ayuda y termina
 465
 466             --version
 467                    saca la información sobre la versión y termina
 468
 469      EJEMPLOS
 470             foo    no hace nada
 471
 472             foo --option
 473                    exactamente igual con `--option'
 474
 475      AUTOR
 476             Creado por U. Programador.
 477
 478      INFORMAR DE ERRORES
 479             Informar de errores a <bug-gnu-utils@gnu.org>.
 480
 481      COPYRIGHT
 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.
 486
 487      VÉASE TAMBIÉN
 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
 491
 492                    info foo
 493
 494             debería llevarle al manual completo.
 495
 496      foo 1.1                          Mayo 2011                          FOO(1)
 497
 498 \1f
 499 File: help2man-es.info.tmp,  Node: Contacto,  Next: Obtención,  Prev: Ejemplo,  Up: Top
 500
 501 8 Informar de errores o sugerencias
 502 ***********************************
 503
 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>.
 507
 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
 511 detalles.
 512
 513 \1f
 514 File: help2man-es.info.tmp,  Node: Obtención,  Prev: Contacto,  Up: Top
 515
 516 9 Obtener ‘help2man’
 517 ********************
 518
 519 La última versión de esta distribución está disponible en internet en
 520 los espejos de GNU:
 521
 522      <http://ftpmirror.gnu.org/help2man/>
 523
 524    Si falla la redirección automática, la lista de espejos está en:
 525
 526      <http://www.gnu.org/order/ftp.html>
 527
 528    O, si hiciera falta, puede usarse el servidor ftp principal de GNU:
 529      <http://ftp.gnu.org/gnu/help2man/>
 530
 531 \1f
 532 Tag Table:
 533 Node: Top\7f1295
 534 Node: Visión de conjunto\7f2233
 535 Node: Invocar help2man\7f3137
 536 Node: recomendaciones para --help\7f6312
 537 Node: Incluir texto\7f10699
 538 Node: Empleo con Makefile\7f12905
 539 Node: Pagínas de manual regionales\7f13963
 540 Node: Ejemplo\7f16097
 541 Node: Contacto\7f18964
 542 Node: Obtención\7f19532
 543 \1f
 544 End Tag Table
 545
 546 \1f
 547 Local Variables:
 548 coding: utf-8
 549 End: