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.