3.4 Invocar lilypond-book

lilypond-book produce un archivo con una de las siguientes extensiones: .tex, .texi, .html o .xml, dependiendo del formato de salida. Todos los archivos .tex, .texi y .xml necesitan un procesado posterior.

Instrucciones específicas para cada formato

LaTeX

Hay dos formas de procesar el documento en LaTeX para su impresión o publicación: hacer un archivo PDF directamente con pdfLaTeX (XeLaTeX, luaLaTeX), o generar un archivo PostScript con LaTeX a través de un traductor de DVI a PostScript como dvips. la primera forma es más sencilla y es la que se recomienda⁶, y cualquiera que sea el método que utilice, podrá convertir fácilmente entre PostScript y PDF con herramientas como ps2pdf y pdf2ps que vienen incluidas con Ghostscript.

Para producir un archivo PDF por medio de pdfLaTeX, utilice:

lilypond-book --pdf miarchivo.pdftex
pdflatex miarchivo.tex

Para producir una salida PDF por medio de LaTeX/dvips/ps2pdf:

lilypond-book miarchivo.lytex
latex miarchivo.tex
dvips -Ppdf miarchivo.dvi
ps2pdf miarchivo.ps

El archivo .dvi creado por este proceso no contiene las cabezas de las notas. Esto es normal; si sigue las instrucciones, las cabezas aparecerán en los archivos .ps y .pdf.

La ejecución de dvips puede dar como resultado algunas advertencias sobre las fuentes tipográficas; son inocuas y se pueden ignorar. Si está ejecutando latex en modo de dos columnas, recuerde añadir -t landscape a las opciones de dvips.

Entornos tales como

\begin{lilypond} … \end{lilypond}

no se interpretan por parte de LaTeX. En su lugar, el programa lilypond-book extrae estos ‘entornos’ como archivos independientes y ejecuta LilyPond sobre ellos. Después, toma las imágenes resultantes y crea un archivo .tex en el que los macros \begin{lilypond}…\end{lilypond} se sustituyen por instrucciones de ‘inserción de gráficos’. A continuación, se ejecuta LaTeX (aunque LaTeX se ha ejecutado anteriormente, lo habrá sido sobre un archivo ‘vacío’ para calcular las dimensiones del papel y el ancho de línea para los fragmentos de LilyPond).

Advertencias y problemas conocidos

La instrucción \pageBreak no funciona dentro de un entorno \begin{lilypond} … \end{lilypond}.

Muchas variables del bloque \paper tampoco funcionan dentro de un entorno \begin{lilypond} … \end{lilypond}. Use \newcommand con \betweenLilyPondSystem en el preámbulo.

\newcommand{\betweenLilyPondSystem}[1]{\vspace{36mm}\linebreak}

Texinfo

Para producir un documento de Texinfo (en cualquier formato de salida), siga el procedimiento normal para Texinfo, esto es: llame a texi2pdf, o bien a texi2dvi o a texi2any, según el formato de la salida que quiera crear. De manera predeterminada, texi2pdf usa pdftex para el procesado, algo que puede verificarse en la salida de la consola. En este caso, ejecute lilypond-book con la opción --pdf de manera que cree fragmentos .pdf en lugar de archivos .eps. pdftex no tiene la capacidad de incluir estos últimos y va a emitir un mensaje de error si se hace de otra manera.

Consulte la documentación de Texinfo para ver más detalles.

Opciones de la línea de órdenes

lilypond-book acepta las siguientes opciones de la línea de órdenes:

-f formato

--format=formato

Especificar el tipo del documento que se va a procesar: html, latex, texi (predeterminado), texi-html o docbook. Si falta esta opción, lilypond-book tratará de detectar el formato automáticamente, véase Extensiones de nombres de archivo. Por el momento, texi-html es lo mismo que texi.

-F filtro

--filter=filtro

Conducir los fragmentos a través de filtro. Con esta opción, lilypond-book no crea los archivos con los fragmentos de música; en lugar de ello modifica el código de los fragmentos insertados en el documento de entrada y emite el archivo resultante, que a su vez se puede procesar con otra ejecución de lilypond-book (sin la opción --filter option). Ejemplo:

lilypond-book --filter='convert-ly --from=2.0.0 -' mi-libro.tely

lilypond-book no acepta las opciones --filter y --process al mismo tiempo.

-h

--help

Imprimir un breve mensaje de ayuda.

-I directorio

--include=directorio

Añadir directorio a la ruta de inclusión. Como lilypond-book busca también los fragmentos ya compilados en la ruta de inclusión, y no los vuelve a escribir en el directorio de salida, en algunos casos es necesario invocar instrucciones de procesado posteriores como texi2any o latex con las mismas opciones -I directorio.

-l nivel_de_registro

--loglevel=nivel_de_registro

Fijar el nivel en que la salida es prolija, al valor nivel_de_registro. Los valores posibles son NONE (nada), ERROR (errores), WARN (advertencias), PROGRESS (avance; predeterminado) y DEBUG (depuración). Si esta opción no se utiliza, y la variable de entorno LILYPOND_BOOK_LOGLEVEL está establecida, se usa su valor como el nivel de registro.

-o directorio

--output=directorio

Colocar los archivos generados en el directorio. La ejecución de lilypond-book genera montañas de pequeños archivos que luego procesará LilyPond. Para evitar toda esta parafernalia en el mismo directorio que la fuente, utilice la opción --output, y cambie a este directorio antes de ejecutar latex o texi2any.

lilypond-book --output=out miarchivo.lytex
cd out
…

--skip-lily-check

Evitar el fracaso si no se encuentra ninguna salida de LilyPond. Se usa para generar la documentación de LilyPond en formato Info sin imágenes.

--skip-png-check

Evitar el fracaso si no se encuentran las imágenes PNG de los archivos EPS. Se usa para la documentación de LilyPond en formato Info sin imágenes.

--lily-output-dir=directorio

Escribir archivos lily-XXX en el directorio directorio y enlazar en el directorio de --output. Use esta opción para ahorrar tiempo de construcción para documentos de distintos directorios que comparten muchos fragmentos idénticos de código.

--lily-loglevel=nivel_de_registro

Fijar el nivel en que la salida es prolija para las llamadas de la instrucción invocada lilypond, al valor nivel_de_registro. Los valores posibles son NONE (nada), ERROR (errores), WARN (advertencias), BASIC (básico), PROGRESS (avance), INFO (información; predeterminado) y DEBUG (depuración). Si no se utiliza esta opción y la variable de entorno LILYPOND_LOGLEVEL está establecida, su valor se usa como nivel de registro.

--info-images-dir=directorio

Dar formato a la salida de Texinfo de manera que Info busque las imágenes de música en directorio.

--inline-vshift=vshift

En el backend LaTeX, usar vshift para mover verticalmente todas las imágenes en línea. vshift es un factor de la altura de la imagen; el valor por omisión es -0.3, moviendo así las imágenes hacia abajo en aproximadamente un tercio de la altura individual respectiva. El factor se puede sobreescribir de forma local con un argumento para la opción inline del fragmento.

--latex-program=prog

Ejecutar el programa prog en vez de latex. Esto es útil si nuestro documento se procesa con xelatex, por ejemplo.

--left-padding=cantidad

Rellenar los fragmentos de LilyPond con espacios por la izquierda.

El valor cantidad viene dado en milímetros relativos al comienzo del pentagrama. El valor predeterminado es 3.0mm.

El ancho de un sistema que está muy ajustado dentro de su rectángulo puede variar, debido a los elementos de notación que están pegados al margen izquierdo, como los números de compás y el nombre del instrumento. El relleno determina la distancia mínima entre el margen izquierdo de las imágenes de los fragmentos y el comienzo de los pentagramas (sin margen añadido); esto da lugar al alineamiento vertical esperado de los fragmentos en el documento maestro.

Además del relleno por la izquierda, esta opción acorta cada línea de pentagrama en la medida determinada por el valor de cantidad. Como consecuencia, cada línea se desplaza visualmente hacia la derecha.

Observe que el valor cantidad, según se utiliza para el relleno, se redondea al valor de un número entero múltiplo de la unidad puntos grandes (bp) para las salidas PostScript y PDF (un bp es 1/72 de pulgada, aproximadamente 0.353mm). Sin embargo, esto no se hace en el lado de LilyPond para acortar la línea de pentagrama. Ello podría dar lugar a un cambio pequeño, pero probablemente sorprendente, en la longitud de la pauta en lugar de cambiar el relleno si el valor cantidad no es un número entero múltiplo de la unidad bp.

-P instrucción

--process=instrucción

Procesar los fragmentos de LilyPond utilizando instrucción. La instrucción predeterminada es lilypond. lilypond-book no acepta las opciones --filter y --process al mismo tiempo.

--pdf

Crear archivos de fragmentos en PDF. Si no está establecido, solo se producen archivos PNG y EPS. Use esta opción si quiere insertar directamente archivos PDF dentro de archivos LaTeX o Texinfo.

--redirect-lilypond-output

De forma predeterminada, la salida de registro se imprime por la consola o terminal. Esta opción redirecciona toda la salida hacia archivos de registro situados en el mismo directorio que los archivos fuente.

--use-source-file-names

Escribir los archivos de salida de los fragmentos de música con el mismo nombre de base que su archivo fuente. Esta opción solo funciona para fragmentos incluidos con la instrucción lilypondfile y solo si los directorios determinados por las opciones --output-dir y --lily-output-dir son distintos.

-V

--verbose

Ser prolijo. Equivale a --loglevel=DEBUG.

-v

--version

Imprimir la información de la versión.

Advertencias y problemas conocidos

La instrucción de Texinfo @pagesizes no se interpreta. De forma similar, las instrucciones de LaTeX que cambian los márgenes y anchos de línea después del preámbulo se ignoran.

Solo se procesa el primer \score de un bloque LilyPond.