man po4a-build (1): Construye documentación traducida

SINOPSIS

po4a-build [-f | --file: fichero
po4a-build [-? | -h | --help | --version]

DESCRIPCIÓN

La meta de po4a-build es facilitar la generación de documentación traducida tanto como lo es generar el contenido sin traducir.

Cuando po4a prepara el contenido traducido bien como POD o DocBook XML, puede usar la orden po4a-build para generar la documentación final. El contenido traducido y sin traducir se generan en un sólo proceso, actualizando los ficheros POT a la vez.

Puede reemplazar las instrucciones de construcción existentes con una sola invocación a po4a-build y un sencillo fichero de configuración usado para decir a po4a-build cómo construir cada elemento y qué paquetes binarios incluirán el contenido traducido y sin traducir.

Una vez generado, el contenido estará en los directorios específicos a cada paquete bajo el BASEDIR (directorio padre) definido en el fichero de configuración. Para un paquete binario «foo», con traducciones al alemán y al francés, el resultado sería el siguiente:

BASEDIR/foo/man/man1/foo.1
BASEDIR/foo/man/de/man1/foo.1
BASEDIR/foo/man/fr/man1/foo.1

Esto facilita incluir todo el contenido generado dentro de los paquetes binarios, con una sola ubicación de instalación.

doc/foo/man/* ./usr/share/man/
doc/foo/html/* ./usr/share/doc/foo/

Esta regla no se tendrá que actualizar al añadir traducciones nuevas, y permite añadir un segundo paquete binario («bar») manteniendo el contenido de éste separado.

Formatos compatibles

A día de hoy, po4a-build es compatible con las siguientes combinaciones:

: 1. DocBook XML para la sección 1.

: 2. DocBook XML para la sección 3.

: 3. DocBook XML para HTML

: 4. POD para la sección 1.

: 5. POD para la sección 3.

: 6. POD para la sección 5.

: 7. POD para la sección 7.

Puede gestionar todos los formatos compatibles y combinaciones posibles con un solo fichero de configuración, po4a-build.conf, y una sola invocación a po4a-build. Consulte po4a-build.conf(5).

CONFIGURACIÓN

Por omisión, po4a-build usa un fichero de configuración, po4a-build.conf, el cual debería estar en el directorio superior del sistema de control de versiones de su paquete. (Use la opción -f para especificar un fichero diferente.) Consulte po4a-build.conf(5).

Ejemplo 1. Ejemplo de fichero de configuración

Dispone de un ejemplo de fichero de configuración en:

/usr/share/doc/po4a/examples/po4a-build.conf.example

Diseño del fichero de configuración

El fichero de configuración consiste de varias secciones: general, compatibilidad con XML/XSL, POD y HTML.

La sección general incluye el nombre y la ubicación del fichero de configuración de po4a (quizá sea mejor nombrarlo po4a.config), el directorio «po/» que contiene la documentación en formatoPO, (a menudo doc/po), el nombre completo del fichero POT empleado para generar las traducciones, el «BASEDIR» para la salida generada, si el paquete contiene páginas de manual en la sección 3 en lugar de sólo en la sección 1, y los nombres de los paquetes binarios que contendrán la salida generada.

La compatibilidad con XML/XSL incluye especificar qué paquetes binarios usan la compatibilidad con XSL a través de la variable «XMLPACKAGES», el el fichero de DocBook en el nivel superior a introducir a xsltproc, y la ubicación de los ficheros XML o DocBook. Puede anular «XSLFILE» si es necesario.

La compatibilidad con POD incluye especificar qué paquetes binarios usan la compatibilidad con POD a través de la variable «PODPACKAGES» y el nombre completo del fichero POD.

La compatibilidad con HTML especifica el subdirectorio a crear bajo «BASEDIR» que contendrá el contenido HTML traducido y sin traducir, y el fichero DocBook usado para generar HTML. Puede anular el fichero «HTMLXSL» si es necesario.

ÓRDENES

--pot-only

Sólo actualiza uno o varios ficheros POT. La opción --pot-only está diseñada para ofrecer la compatibilidad con paquetes que incluyen todos los ficheros POT en el paquete de fuentes. Aquellos paquetes que usan Autotools pueden añadir fácilmente el fichero POT a través de «EXTRA_DIST», pero aquellos paquetes que emplean un «Makefile» o algunos asistentes de compilación de sistemas de control de versiones encontrarán extraño añadir el fichero POT (que es un fichero generado) sin poner el fichero POT en el sistema de control de versiones. Para evitar este trabajo feo e innecesario, po4a-build puede actualizar el o los ficheros POT al principio de la construcción, de forma que dpkg-source los incluya en el archivo tar de fuentes.

Ejemplo 2. Ejemplo de svn-buildpackage

svn-buildpackage tiene compatibilidad explícita para esta clase de añadidos, usando la propiedad useNativeDist de SVN y el «target» de Make native-dist.

# Añade el fichero POT al archivo tar de fuentes
native-dist: Makefile
        po4a-build --pot-only

$ svn propset useNativeDist 1 debian

-h|--help

: Muestra el mensaje de uso y cierra

--version

: Muestra el mensaje de uso y cierra

OPCIONES

-f|--file fichero

: Anula el fichero de configuración predefinido de poa-build (po4a-build.conf) e introduce el suyo.

AUTOR

po4a-build fue creado por Neil Williams <[email protected]>.

Neil Williams escribió esta página de manual. <[email protected]>