Resumen
Además de la simple generación de documentos, están disponibles muchas características avanzadas que permiten al usuario personalizar con facilidad los formatos de salida o generar un conjunto de manuales con un único comando. Aquí detallaremos todo eso.
Un manual final (en un
formato legible por el usuario) simplemente se identifica por su
nombre seguido de una extensión de formato. Cuatro formatos con
cuatro extensiones están disponibles para un documento DocBook
en
Borges:
Tabla 3.1. Formatos de salida de Borges
Sabiendo eso, todo lo
que debe hacer es ejecutar make para obtener la
salida deseada. Por ejemplo, si desea obtener el documento
Install-guide-RPM
a partir del super-documento
Install-guide
en inglés, en formato PDF,
simplemente ejecute:
make -C manuals/Install-guide/ Install-guide-RPM.pdf LANG=en
Cuando uno necesita publicar todos los manuales disponibles en todos los idiomas para su proyecto, compilarlos uno tras otro en todos los formatos puede resultar tedioso. Es por esto que Borges proporciona un objetivo para compilar automáticamente cualquier combinación de manual-idioma-formato.
La sinópsis de este comando es:
make all SUBDOCS="<lista_docs>" LANGS=""<lista_idiomas>" FORMATS=""<lista_formatos>"
donde:
es la lista de
pares de super-documentos/documentos que desea generar. Si
desea obtener los manuales
Install-guide-RPM
e
Install-guide-tar
a partir del
super-documento Install-guide
, deberá
utilizar SUBDOCS="Install-guide/Install-guide-RPM
Install-guide/Install-guide-tar"
es la lista de
idiomas en los cuales obtener los manuales. Use
LANGS="en fr es"
para obtener todos
los manuales en inglés, francés y español.
es la lista de
extensiones en las cuales compilar los manuales. Si está
interesado en salida PDF y HTML plano, use
FORMATS="pdf flat.html"
Con este ejemplo, terminaríamos con la línea de comandos siguiente:
make all SUBDOCS="Install-guide/Install-guide-RPM Install-guide/Install-guide-tar" \ LANGS="en fr es" FORMATS="pdf flat.html"
Lo cual resultaría en 2x3x2 = 12 manuales en
Outputs/
.
Cuando está trabajando en la escritura y/o traducción de un módulo, muy seguido desea echar un vistazo al mismo en uno de los formatos de salida soportados. La característica de compilación de un único módulo de Borges le permite hacer esto sin la necesidad de compilar todo el documento que contiene al módulo en cuestión, de esa manera le deja más tiempo para hacer su trabajo en vez de esperar tiempos largos de compilación de libros.
La sinópsis del comando para compular un único módulo es:
make -C manuals/module <module_name>.<output_format> [LANG=ll]
Note que el directorio para la compilación de un único módulo
siempre es manuals/module
sin importar a qué
documento pertenezca el módulo. Este directorio se crea
automáticamente cuando se inicializa Borges. Toda la salida
de la compilación de un único módulo termina allí.
El parámetro
LANG=ll
es opcional y se utiliza para forzar que
la compilación ocurra en un idioma distinto al predeterminado.
ll
es el código ISO de dos letras minúsuclas
del idioma.
Por ejemplo, luego de ejecutar:
make -C manuals/module borges-compile-features-sect1.pdf LANG=en
terminará con el archivo PDF
manuals/module/borges-compile-features-sect1.pdf
con el contenido del módulo
borges-compile-features-sect1
en inglés.