Doc-es: update Usage/Running.

[lilypond.git] / Documentation / es / usage / running.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-

@ignore
    Translation of GIT committish: cd1ac38996d3de35770ea31f819b392fe686bf39

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.19.21"


@node Ejecutar LilyPond
@chapter Ejecutar LilyPond
@translationof Running LilyPond

Este capítulo detalla los aspectos técnicos de la ejecución de
LilyPond.

@menu
* Utilización normal::
* Utilización desde la línea de órdenes::
* Mensajes de error::
* Errores comunes::
@end menu


@node Utilización normal
@section Utilización normal
@translationof Normal usage

Casi todos los usuarios ejecutan LilyPond por medio de un interfaz
gráfico; consulte @rlearning{Primeros pasos} si no lo ha leído aún.


@node Utilización desde la línea de órdenes
@section Utilización desde la línea de órdenes
@translationof Command-line usage

Esta sección contiene información adicional sobre el uso de LilyPond
en la línea de órdenes.  Esta forma puede ser preferible para pasarle
al programa algunas opciones adicionales.  Además, existen algunos
programas complementarios @q{de apoyo} (como @code{midi2ly}) que sólo
están disponibles en la línea de órdenes.

Al hablar de la @q{línea de órdenes}, nos referimos a la consola del
sistema operativo.  Los usuarios de Windows posiblemente estén más
familiarizados con los términos @q{ventana de MS-DOS} o @q{línea de
comandos}; Los usuarios de MacOS@tie{}X puede que estén más
familiarizados con los términos @q{terminal} o @q{consola}.  Éstos
podrían requerir algunas configuraciones adicionales y deberían
consultar también el apartado @rweb{MacOS X}.

La descripción del uso de esta parte de los sistemas operativos se
sale del ámbito de este manual; le rogamos que consulte otros
documentos sobre este tema si no le resulta familiar la línea de
órdenes.

@menu
* Invocar a LilyPond::
* Opciones de LilyPond básicas de la línea de órdenes::
* Opciones avanzadas de línea de órdenes para LilyPond::
* Variables de entorno::
* LilyPond en una jaula de chroot::
@end menu

@node Invocar a LilyPond
@unnumberedsubsec Invocar @command{lilypond}
@translationof Invoking lilypond

El ejecutable @command{lilypond} se puede llamar desde la línea de
órdenes de la siguiente manera:

@example
lilypond [@var{opción}]@dots{} @var{archivo}@dots{}
@end example

Cuando se invoca con un nombre de archivo sin extensión, se prueba en
primer lugar con la extensión @file{.ly}.  Para leer la entrada desde
stdin, utilice un guión (@code{-}) en sustitución de @var{archivo}.

Cuando se procesa @file{archivo.ly}, la salida resultante son los
archivos @file{archivo.ps} y @file{archivo.pdf}.  Se pueden
especificar varios archivos; cada uno de ellos se procesará de forma
independiente@footnote{El estado de GUILE no se restablece después de
procesar un archivo @code{.ly}, por lo que debe tener cuidado de no
modificar ningún valor predeterminado desde dentro de Scheme.}.

Si @file{archivo.ly} contiene más de un bloque @code{\score}, el resto
de las partituras se obtendrán como salida en archivos numerados,
empezando por @file{archivo-1.pdf}.  además, el valor de
@code{output-suffix} (sufijo de salida) se insertará entre el nombre
base y el número.  Un archivo de entrada que contenga

@example
#(define output-suffix "violin")
\score @{ @dots{} @}
#(define output-suffix "cello")
\score @{ @dots{} @}
@end example

@noindent
produce como salida @var{base}@file{-violin.pdf} y
@var{base}@file{-cello-1.pdf}.


@unnumberedsubsubsec Uso de LilyPond con las posibilidades básicas del shell

Dado que LilyPond es una aplicación de consola, las posibilidades
del @q{shell} usado para la llamada a LilyPond también pueden
aprovecharse.

Por ejemplo:

@example
lilypond *.ly
@end example

@noindent
procesa todos los archivos de LilyPond dentro del directorio
actual.

También puede ser útil redireccionar la salida de consola
(p.ej. hacia un archivo):

@example
lilypond file.ly 1> salida_estandar.txt

lilypond file.ly 2> error_estandar.txt

lilypond file.ly &> todo.txt
@end example

@noindent
Redirecciona la salida @q{normal}, solo los @q{errores} o
@q{todo}, respectivamente, hacia un archivo de texto.  Consulte la
documentación de su shell concreto, Command (Windows), las
aplicaciones Terminal o Console (MacOS X) para ver si el
redireccionamiento de la salida está contemplado o si la sintaxis
es distinta.

El ejemplo siguiente busca y procesa todos los archivos de
entradas que estén en el directorio actual y en todos los que
están por debajo de él, recursivamente.  Los archivos de salida se
pondrán en el mismo directorio desde el que se ejecutó la
instrucción, en lugar de aquellos en los que estaban los archivos
de entrada originales.

@example
find . -name '*.ly' -exec lilypond '@{@}' \;
@end example

@noindent
También debe funcionar para los usarios de MacOS@tie{}X.

Un usuario de Windows haría los siguiente:

@example
forfiles /s /M *.ly /c "cmd /c lilypond @@file"
@end example

@noindent
introduciendo esstas instrucciones desde un @code{indicador de
órdenes} que normalmente está en @code{Inicio > Accessorios >
Símbolo del sistema} o para los usuarios de la versión 8,
escribiendo en la ventana de búsqueda @q{indicador de órdenes}.

De forma alternativa, una ruta explícita al nivel superior de su
carpeta que contenga todas las subcarpetas con archivos de entrada
en su interior se puede especificat mediante la opción @code{/p};

@example
forfiles /s /p C:\Documentos\MisPartituras /M *.ly /c "cmd /c lilypond @@file"
@end example

Si el nombre de la ruta del directorio de nivel superior contiene
espacios, entonces es necesario incluir toda la ruta entre
comillas:

@example
forfiles /s /p "C:\Documentos\Mis Partituras" /M *.ly /c "cmd /c lilypond @@file"
@end example


@node Opciones de LilyPond básicas de la línea de órdenes
@unnumberedsubsec Opciones de LilyPond básicas de la línea de órdenes
@translationof Basic command line options for LilyPond

@cindex Invoca a @command{lilypond}
@cindex opciones de la línea de órdenes para @command{lilypond}
@cindex opciones, línea de órdenes
@cindex opciones

Están contempladas las siguientes opciones:

@table @code

@item -b, --bigpdfs
@cindex bigpdfs

Los archivos PDF generados serán mucho más grandes de lo normal (a
causa de la poca o ninguna optimización de las fuentes
tipográficas).  Sin embargo, si dos o más archivos PDF se incluyen
dentro de @w{@code{pdftex}}, @w{@code{xetex}} o @w{@code{luatex}}
los documentos producidos pueden procesarse después a través de
ghostscript (mezclando los datos de tipografías duplicados) dando
como resultado archivos PDF @emph{significativamente} más
pequeños.

@example
lilypond -b archivo
@end example

Después, ejecute @code{ghostscript};

@example
gs -q -sDEVICE=pdfwrite -o gsout.pdf archivo.pdf
@end example

Se puede entonces usar @code{pdfsizeopt.py} para optimizar aún más
el tamaño del archivo:

@example
pdfsizeopt.py --use-multivalent=no gsout.pdf final.pdf
@end example

@item -d, --define-default=@var{variable}=@var{valor}
Véase @ref{Opciones avanzadas de línea de órdenes para LilyPond}.

@cindex Scheme, evaluación de expresiones
@cindex expresiones de Scheme, evaluación

@item -e, --evaluate=@var{expresión}
Evaluar la @var{expresión} de Scheme antes de analizar los archivos
@file{.ly}.  Se pueden pasar varias opciones @option{-e}, que se
evaluarán en secuencia.

La expresión se evaluará en el módulo @code{guile-user}, de manera que
si quiere usar definiciones dentro de @var{expresión}, debe utilizar

@example
lilypond -e '(define-public a 42)'
@end example

@noindent
en la línea de órdenes, e incluir

@example
#(use-modules (guile-user))
@end example

@noindent
al principio del archivo @file{.ly}.

@warning{Los usuarios de Windows deben utilizar comillas dobles en lugar de apóstrofos simples.}

@cindex output, format
@cindex format, output

@item -f, --format=@var{format}
which formats should be written.  Choices for @code{format} are
@code{ps}, @code{pdf}, and @code{png}.

Example: @code{lilypond -fpng @var{filename}.ly}

@noindent
Para los formatos @code{svg} y @code{eps} utilice
la opción @code{-dbackend}.
Véase @ref{Opciones avanzadas de línea de órdenes para LilyPond}.

@item -h, --help
Mostrar un resumen de las formas de utilización.

@item -H, --header=@var{CAMPO}
Volcar un campo de cabecera al archivo @file{NOMBREBASE.@var{CAMPO}}

@item -i, --init=@var{archivo}
Establecer el archivo de inicio a @var{archivo} (predeterminado:
@file{init.ly}).

@cindex archivos, búsqueda de
@cindex búsqueda, ruta de

@item -I, --include=@var{directorio}
Añadir el @var{directorio} a la ruta de búsqueda de archivos de
entrada.

Se pueden escribir varias opciones -I.  La búsqueda se inicia en el
primer directorio definido, y si el archivo que se debe incluir no se
encuentra, la búsqueda continúa en los directorios siguientes.

@cindex chroot, ejecutar dentro de una jaula

@item -j, --jail=@var{usuario},@var{grupo},@var{jaula},@var{directorio}
Ejecutar @command{lilypond} en una jaula de chroot.

La opción @option{--jail} (jaula) proporciona una alternativa más
flexible a la opción @option{-dsafe} cuando el proceso de tipografía de
LilyPond está disponible a través de un servidor web o cuando LilyPond
ejecuta instrucciones enviadas por fuentes externas
(véase @ref{Opciones avanzadas de línea de órdenes para LilyPond}).

La opción @option{--jail} funciona cambiando la raíz de
@command{lilypond} a @var{jaula} justo antes de comenzar el proceso de
compilación en sí.  Entonces se cambian el usuario y el grupo a los
que se han dado en la opción, y el directorio actual se cambia a
@var{directorio}.  Esta instalación garantiza que no es posible, al
menos en teoría, escapar de la jaula.  Observe que para que funcione
@option{--jail}, se debe ejecutar @command{lilypond} como root, lo que
normalmente se puede hacer de una forma segura utilizando
@command{sudo}.

La instalación de una jaula puede ser un asunto relativamente
complejo, pues debemos asegurarnos de que LilyPond puede encontrar
@emph{dentro} de la propia jaula todo lo que necesita para poder
compilar la fuente.  Una típica configuración de jaula de chroot
consta de los siguientes elementos:

@table @asis

@item Preparar un sistema de archivos separado
Se debe crear un sistema de archivos separado para LilyPond, de forma
que se pueda montar con opciones seguras como @code{noexec},
@code{nodev} y @code{nosuid}.  De esta forma, es imposible ejecutar
programas o escribir directamente a un dispositivo desde LilyPond.  Si
no quiere crear una partición separada, tan sólo tiene que crear un
archivo de un tamaño razonable y usarlo para montar un dispositivo
loop.  El sistema de archivos separado garantiza también que LilyPond
nunca pueda escribir en un espacio mayor del que se le permita.

@item Preparar un usuario separado
Se debe usar un usuario y grupo separados (digamos
@code{lily}/@code{lily}) con bajos privilegios para ejecutar LilyPond
dentro de la jaula.  Debería existir un solo directorio con permisos
de escritura para este usuario, y debe pasarse en el valor
@var{directorio}.

@item Preparar la jaula
LilyPond necesita leer algunos archivos mientras se ejecuta.  Todos
estos archivos se deben copiar dentro de la jaula, bajo la misma ruta
en que aparecen en el sistema de archivos real de root.  Todo el
contenido de la instalación de LilyPond (por ejemplo
@file{/usr/share/lilypond}) se debe copiar.

Si surgen problemas, la forma más sencilla de rastrearlos es ejecutar
LilyPond usando @command{strace}, lo que le permitirá determinar qué
archivos faltan.

@item Ejecutar LilyPond
Dentro de una jaula montada con @code{noexec} es imposible ejecutar
ningún programa externo.  Por tanto, LilyPond se debe ejecutar con un
backend que no necesite tal programa.  Como ya hemos mencionado, se
debe ejecutar con privilegios del superusuario (que por supuesto
perderá inmediatamente), posiblemente usando @command{sudo}.  También
es una práctica recomendable limitar el número de segundos de tiempo
de CPU que LilyPond puede usar (p.ej., usando
@command{ulimit@tie{}-t}), y, si su sistema operativo lo contempla, el
tamaño de la memoria que se puede reservar.  Véase también
@ref{LilyPond en una jaula de chroot}.

@end table

@cindex loglevel
@cindex registro, nivel de
@cindex salida prolija, fijar el nivel

@item -l, --loglevel=@var{LEVEL}
Fijar el grado en que la salida de consola es prolija al nivel
@var{LEVEL}. Los valores posibles son:

@table @code

@item NONE
Ninguna salida en absoluto, ni siquiera mensajes de error.

@item ERROR
Solamente mensajes de error, no advertencias o indicaciones de progreso.

@item WARN
Advertencias y mensajes de error, no de progreso.

@item BASIC_PROGRESS
Mensajes de progreso básicos (éxito), advertencias y errores.

@item PROGRESS
Todos los mensajes de progreso, advertencias y errores.

@item INFO (predeterminado)
Mensajes de progreso, advertencias, errores e información de ejecución
adicional.

@item DEBUG
Todos los mensajes posibles, incuida la información de depuración
prolija.
@end table

@cindex carpeta, dirigir la salida hacia
@cindex salida, establecer el nombre del archivo de

@item -o, --output=@var{ARCHIVO} o @var{CARPETA}
Establecer el nombre del archivo de salida predeterminado a
@var{ARCHIVO} o, si existe una carpeta con ese nombre, dirigir la
salida hacia @var{CARPETA}, tomando el nombre de archivo del documento
de entrada.  Se añade el sufijo correspondiente (por ejemplo,
@code{.pdf} para PDF) en los dos casos.

@cindex PS (Postscript), salida
@cindex Postscript (PS), salida
@cindex salida, PS (Postscript)

@item --ps
Generar PostScript.

@cindex PNG (Portable Network Graphics), salida
@cindex salida, PNG (Portable Network Graphics)

@item --png
Generar imágenes de las páginas en formato PNG.  Esto implica
@option{--ps}.  La resolución en PPP de la imagen se puede establecer
con
@example
-dresolution=110
@end example

@cindex PDF (formato de documento portátil), salida de
@cindex salida, PDF (formato de documento portátil)

@item --pdf
Generar PDF.  Implica @option{--ps}.

@item -v, --version
Mostrar la información de la versión.

@item -V, --verbose
Ser prolijo: mostrar las rutas completas de todos los archivos que se
leen, y dar información cronométrica.

@item -w, --warranty
Mostrar la garantía con que viene GNU LilyPond (¡no viene con
@strong{NINGUNA GARANTÍA}!).

@end table


@node Opciones avanzadas de línea de órdenes para LilyPond
@unnumberedsubsec Opciones avanzadas de línea de órdenes para LilyPond
@translationof Advanced command line options for LilyPond

@table @code

@item -d@var{[option-name]}=@var{[value]},
--define-default=@var{[option-name]}=@var{[value]}
Establece la función de Scheme interna equivalente a @var{valor}.
Por ejemplo:

@example
-dbackend=svg
@end example

Si no se proporciona ningún @var{valor}, se usa el valor predeterminado.
Para desactivar una opción se puede anteponer @code{no-} a la
@var{variable}.  Por ejemplo:

@cindex point and click, command line

@example
-dpoint-and-click=#f
@end example

@noindent
is the same as
@example
-dno-point-and-click
@end example
@end table

@noindent Están contempladas las siguientes opciones junto a sus respectivos
valores predeterminados:

@multitable @columnfractions .33 .16 .51
@item @strong{Símbolo}
@tab @strong{Valor}
@tab @strong{Explicación/Opciones}

@item @code{anti-alias-factor} (factor de antialias)
@tab @code{1}
@tab Renderizar a mayor resolución (utilizando el factor dado)
y reducir la escala del resultado para así evitar @q{escaleras} en
las imágenes @code{PNG}.

@item @code{aux-files} (archivos auxiliares)
@tab @code{#t}
@tab Crear archivos @code{.tex}, @code{.texi} y @code{.count}
cuando se usa con la opción de @q{back-end} @code{EPS}.

@item @code{backend}
@tab @code{ps}
@tab Es el ajuste predeterminado.
Los archivos Postscript (la opción predeterminada) incluyen las
fuentes tipográficas @code{TTF}, @code{Type1} y @code{OTF}.  No se
hace ningún subconjunto de estas fuentes.  Tenga en cuenta que el
uso de conjuntos de caracteres @q{orientales} puede dar lugar a
archivos muy grandes.

@item
@tab @code{eps}
@tab Usado como opción predeterminada por la instrucción @command{lilypond-book}.
Vuelca cada página al mismo tiempo como un solo archivo con todas
las ṕaginas y fuentes tipográficas incluidas y como archivos
postscript separados para cada página pero sin las fuentes
tipográficas incluidas.

@item
@tab @code{null}
@tab No producir ninguna partitura impresa a la salida; tiene el mismo
efecto que @code{-dno-print-pages}.

@item
@tab @code{scm}
@tab Volcado de las instrucciones de dibujo internas basadas en Scheme, en
bruto.

@item
@tab @code{svg}
@tab Gráficos vectoriales escalables.
Por cada página de la salida, se crea un solo archivo @code{SVG}.
Los glifos musicales se codifican como gráficos vectoriales,
pero las fuentes tipográficas del texto
@emph{no} se incrustan en los archivos SVG.
Cualquier visor de SVG necesita que las fuentes de texto
correspondientes estén disponibles para
la correcta representación tanto del texto como de la letra. Se
recomienda no utilizar @q{alias} ni @q{listas} de fuentes
tipográficas por si el visor de SVG no es capaz de
manejarlas.  Al usar archivos de fuente abierta para la web
@emph{Web Open Font Format} (WOFF), es necesario indicar la opción
@code{--svg-woff}.
@end multitable

@noindent
@strong{Nota para el backend de salida svg:}
En la salida SVG, LilyPond usa por defecto los valores
de @code{font-family} genéricos @code{serif}, @code{sans-serif}, o
@code{monospace}.  Por tanto, al usar el
backend @code{svg} debemos definir explícitamente
las fuentes predeterminadas deseadas en el archivo de entrada:

@quotation
@verbatim
\paper  {
  #(define fonts
    (make-pango-font-tree "TeX Gyre Schola"
                          "TeX Gyre Heros"
                          "TeX Gyre Cursor"
                          (/ staff-height pt 20)))
}
@end verbatim
@end quotation

Véase también @ruser{Fuentes tipográficas del documento completo}.

@multitable @columnfractions .33 .16 .51
@item @code{check-internal-types}
@tab @code{#f}
@tab Comprobar el tipo de cada asignación de propiedades.

@item @code{clip-systems} (recortar los sistemas)
@tab @code{#f}
@tab Extraer fragmentos de música de la partitura.  Requiere que la función
@code{clip-regions} esté definida dentro del bloque
@code{\layout}.  Véase @ruser{Extracción de fragmentos de música}.
No se extrae ningún fragmento si se usa con la copción
@option{-dno-print-pages}.

@item @code{datadir} (directorio de datos)
@tab
@tab Prefijo de los archivos de datos (sólo lectura).

@item @code{debug-gc}
@tab @code{#f}
@tab Volcar estadísticas de depuración de memoria.

@item @code{debug-gc-assert-parsed-dead}
@tab @code{#f}
@tab Para la depuración de memoria: asegurarse de que todas las referencias
a objetos analizados están muertas.  Es una opción interna, y se
activa automáticamente para @code{`-ddebug-gc'}.

@item @code{debug-lexer}
@tab @code{#f}
@tab Depuración del analizador léxico flex.

@item @code{debug-page-breaking-scoring}
@tab @code{#f}
@tab Volcar las partituras para muchas configuraciones de saltos de página
diferentes.

@item @code{debug-parser}
@tab @code{#f}
@tab Depuración del analizador sintáctico bison.

@item @code{debug-property-callbacks}
@tab @code{#f}
@tab Depuración de las cadenas cíclicas de funciones de callback.

@item @code{debug-skylines}
@tab @code{#f}
@tab Depuración de las líneas de horizonte.

@item @code{delete-intermediate-files}
@tab @code{#t}
@tab Eliminar los archivos intermedios @code{.ps} inútiles ques e crean
durante la compilación.

@item @code{dump-cpu-profile}
@tab @code{#f}
@tab Volcar información de cuenta de tiempo (dependiente del sistema).

@item @code{dump-profile}
@tab @code{#f}
@tab Volcar de la información de memoria y de tiempo para cada archivo.

@item @code{dump-signatures}
@tab @code{#f}
@tab Volcar las firmas de salida de cada sistema.  Usado para las pruebas
de regresión.

@item @code{embed-source-code}
@tab @code{#f}
@tab Empotrar los archivos de entrada en código de LilyPond
dentro del documento PDF generado.

@item @code{eps-box-padding}
@tab @code{#f}
@tab Rellenar el borde izquierdo de la caja contenedora del EPS de salida
en la cantidad dada (en mm).

@item @code{font-export-dir}
@tab @code{#f [dir]}
@tab Directorio para exportar las fuentes como archivos de Postscript.

@item @code{gs-load-fonts}
@tab @code{#f}
@tab Cargar las fuentes tipográficas a través de Ghostscript.

@item @code{gs-load-lily-fonts}
@tab @code{#f}
@tab Cargar sólo las fuentes de LilyPond por medio de Ghostscript.

@item @code{gs-never-embed-fonts}
@tab @code{#f}
@tab Hacer que Ghostscript incruste solo las fuentes TrueType y no cualquier otro formato de fuente.

@item @code{gui}
@tab @code{#f}
@tab Se ejecuta silenciosamente y se redirige toda la salida a un archivo
de registro.
@end multitable

@noindent
@strong{Nota para los usuarios de Windows:} De manera predeterminada,
@code{lilypond.exe} dirige toda la salida de la información de avance
hacia la ventana de consola, @code{lilypond-windows.exe} no lo hace y
devuelve un indicador del sistema, sin ninguna indicación del avance,
inmediatamente en la línea de órdenes.  La opción @option{-dgui} se
puede usar en este caso para redirigir la salida a un archivo de
registro.

@multitable @columnfractions .33 .16 .51
@item @code{help}
@tab @code{#f}
@tab Mostrar esta ayuda.

@item @code{include-book-title-preview}
@tab @code{#t}
@tab Incluir los títulos de libro en las imágenes de vista previa.

@item @code{include-eps-fonts}
@tab @code{#t}
@tab Incluir las fuentes tipográficas en los archivos EPS de cada uno de
los sistemas.

@item @code{include-settings}
@tab @code{#f}
@tab Incluir el archivo de los ajustes globales, se incluye antes de que la
partitura se procese.

@item @code{job-count}
@tab @code{#f}
@tab Procesar en paralelo, usando el número de tareas dado.

@item @code{log-file}
@tab @code{#f [file]}
@tab Si se da una cadena @code{NOMBRE} como segundo argumento,
redirigir la salida al archivo de registro @code{NOMBRE.log}.

@item @code{max-markup-depth}
@tab @code{1024}
@tab Profundidad máxima del árbol de marcado. Si un marcado tiene más niveles,
suponer que no terminará por sí mismo, imprimiento una advertencia y
devolviendo en su lugar un elemento de marcado nulo.

@item @code{midi-extension}
@tab @code{"midi"}
@tab Fijar la extensión de archivo predeterminada para el archivo de salida
MIDI a la cadena dada.

@item @code{music-strings-to-paths}
@tab @code{#f}
@tab Convertir las cadenas de texto a rutas cuando los glifos pertenecen a
una fuente de tipografía musical.

@item @code{paper-size}
@tab @code{\"a4\"}
@tab Establecer el tamaño predeterminado del papel.  Observe que la cadena
debe ir encerrada entre comillas dobles.

@item @code{pixmap-format}
@tab @code{png16m}
@tab Fijar el formato de salida de Ghostscript para las imágenes de píxeles.

@item @code{point-and-click}
@tab @code{#t}
@tab Añadir enlaces de @q{apuntar y pulsar} a la salida PDF y SVG. Véase
@ref{Apuntar y pulsar}.

@item @code{preview}
@tab @code{#f}
@tab Crear imágenes de vista previa además de la salida normal.
@end multitable

@noindent
Esta opción está contemplada por todos los @q{back-ends}: @code{pdf},
@code{png}, @code{ps}, @code{eps} y @code{svg}, pero no por
@code{scm}.  Genera un archivo de salida, en la forma
@code{miArchivo.preview.extensión}, que contiene los títulos y el
primer sistema de la música.  Si se están utilizando bloques
@code{\book} o @code{\bookpart}, aparecen en la salida los títulos de
@code{\book}, @code{\bookpart} o @code{\score}, incluido el primer
sistema de cada bloque @code{\score} si la variable de @code{\paper}
@code{print-all-headers} está fijada al valor @code{#t}.

Para suprimir la salida usual, utilice las opciones
@option{-dprint-pages} o @option{-dno-print-pages} según sus
necesidades.

@multitable @columnfractions .33 .16 .51
@item @code{print-pages}
@tab @code{#t}
@tab Generar páginas completas (es la opción predeterminada).  Es útil
@option{-dno-print-pages} en combinación con @option{-dpreview}.

@item @code{profile-property-accesses}
@tab @code{#f}
@tab Conservar las estadísticas de las llamadas de función
@code{get_property()}.

@item @code{protected-scheme-parsing}
@tab @code{#t}
@tab Continuar cuando se captan en el analizador sintáctico errores del
Scheme empotrado.  Si se fija a @code{#f}, detenerse cuando haya
errores e imprimir un registro de traza de pila.

@item @code{read-file-list}
@tab @code{#f [archivo]}
@tab Especificar el nobmre de un archivo que contiene una lista de archivos
de entrada para procesar.

@item @code{relative-includes}
@tab @code{#f}
@tab Cuando se procesa una instrucción @code{\include} command, buscar el
archivo incluido de forma relativa al archivo actual (en lugar del
archivo principal).

@item @code{resolution}
@tab @code{101}
@tab Fijar la resolución para generar imágenes de píxeles @code{PNG} al
valor dado (en ppp).

@item @code{safe}
@tab @code{#f}
@tab No confiar en la entrada @code{.ly}.
@end multitable

@noindent
Cuando el servicio de tipografía está disponible a través de un
servidor web, @b{SE DEBEN} pasar las opciones @option{--safe} o
@option{--jail}.  La opción @option{--safe} evita que el código de
Scheme monte un desastre, p.ej.:

@quotation
@verbatim
#(s ystem "rm -rf /")  % demasiado peligroso para escribirlo correctamente
{
  c4^$(ly:gulp-file "/etc/passwd") % malicioso aunque no tan destructivo
}
@end verbatim
@end quotation

La opción @option{-dsafe} funciona evaluando las expresiones de Scheme
en línea dentro de un módulo seguro especial.  Deriva del módulo
@file{safe-r5rs} de GUILE, pero además añade unas cuantas funciones de
la API de LIlyPond que están relacionadas en @file{scm/safe-lily.scm}.

Además, el modo seguro prohíbe las directivas @code{\include} y
desactiva la utilización de barras invertidas en las cadenas de
@TeX{}.  Asimismo, no es posible importar variables de LilyPond dentro
de Scheme cuando se está en modo seguro.

@option{-dsafe} @emph{no} detecta la sobreutilización de recursos, por
lo que aún es posible hacer que el programa se cuelgue
indefinidamente, por ejemplo suministrando estructuras de datos
cíclicas en el backend.  Por ello, si está usando LilyPond en un
servidor web accesible públicamente, el proceso se debe limitar tanto
en el uso de memoria como de CPU.

El modo seguro evita que se puedan compilar muchos fragmentos de
código útiles.

La opción @option{--jail} es una alternativa más segura aún, pero
requiere más trabajo para su configuración.  Véase
@ref{Opciones de LilyPond básicas de la línea de órdenes}.

@multitable @columnfractions .33 .16 .51
@item @code{separate-log-files}
@tab @code{#f}
@tab Para los archivos de entrada @code{ARCHIVO1.ly}, @code{ARCHIVO2.ly},
etc. sacar los datos de registro hacia los archivos @code{ARCHIVO1.log},
@code{ARCHIVO2.log}@dots{}

@item @code{show-available-fonts}
@tab @code{#f}
@tab Listar todos los nombres de las fuentes tipográficas disponibles.

@item @code{strict-infinity-checking}
@tab @code{#f}
@tab Forzar una terminación abrupta si se encuentran las excepciones de
punto flotante @code{Inf} y @code{NaN}.

@item @code{strip-output-dir}
@tab @code{#t}
@tab No usar los directorios de los archivos de entrada al construir los
nombres de los archivos de salida.

@item @code{strokeadjust}
@tab @code{#f}
@tab Forzar el ajuste de los trazos de PostScript.  Esta opción es
relevante principalmente cuando se genera un PDF a partir de la
salida de PostScript (el ajuste del trazo está por lo general
activado automáticamente para dispositivos de mapa de puntos de
baja resolución).  Sin esta opción, los visores de PDF tienden a
producir anchuras de plica muy poco consistentes a las
resoluciones típicas de las pantallas de ordenador.  La opción no
afecta de forma muy significativa a la calidad de la impresión y
causa grandes incrementos en el tamaño del archivo PDF.

@item @code{svg-woff}
@tab @code{#f}
@tab Esta opción es necesaria al usar archivos de fuente abierta para la Web,
Web Open Font Format (WOFF) con la instrucción de backend
@code{svg}.  Se crea un solo archivo SVG para cada página de
salida.  Aparte de los glifos musicales propios de LilyPond, no se
incluye ninguna otra información de fuente tipográfica.  Todo
visor de SVG necesita, por ello, tener las fuentes disponibles
para la representación correcta tanto del texto como de la letra.
Asimismo se recomienda no usar alias de fuentes ni listas, por si
el visor de SVG no es capaz de manejarlos.

@item @code{trace-memory-frequency}
@tab @code{#f}
@tab Registrar el uso de células de Scheme esta cantidad de veces por
segundo.  Volcar los resultados en @code{ARCHIVO.stacks} y en
@code{ARCHIVO.graph}.

@item @code{trace-scheme-coverage}
@tab @code{#f}
@tab Registrar la cobertura de los archivos de Scheme en @code{ARCHIVO.cov}.

@item @code{verbose}
@tab @code{#f}
@tab Salida prolija, es decir el nivel de registro en DEBUG (sólo lectura).

@item @code{warning-as-error}
@tab @code{#f}
@tab Cambiar todos los mensajes de advertencia y de @q{error de
programación} a errores.
@end multitable


@node Variables de entorno
@unnumberedsubsec Variables de entorno
@translationof Environment variables

@cindex LANG
@cindex LILYPOND_DATADIR

@command{lilypond} reconoce las siguientes variables de entorno:
@table @code
@item LILYPOND_DATADIR
Especifica un directorio en el que los mensajes de localización y de
datos se buscarán de forma predeterminada.  El directorio debe
contener subdirectorios llamados @file{ly/}, @file{ps/}, @file{tex/},
etc.

@item LANG
Selecciona el idioma de los mensajes de advertencia.

@item LILYPOND_LOGLEVEL
Nivel de registro predeterminado.  Si LilyPond se llama sin ningún
nivel de registro explícito (es decir, sin opción de línea de órdenes
@option{--loglevel}), se usa este valor.

@item LILYPOND_GC_YIELD
Una variable, como porcentaje, que ajusta el comportamiento de la
administración de memoria.  Con valores más altos, el programa usa más
memoria; con valores más bajos, usa más tiempo de CPU.  El valor
predeterminado es @code{70}.

@end table


@node LilyPond en una jaula de chroot
@unnumberedsubsec LilyPond en una jaula de chroot
@translationof LilyPond in chroot jail

La preparación del servidor para que ejecute LilyPond en una jaula de
chroot es una tarea muy complicada.  Los pasos están relacionados más
abajo.  Los ejemplos que aparecen en cada uno de los pasos son válidos
para Ubuntu GNU/Linux, y pueden requerir el uso de @code{sudo} según
corresponda.

@itemize

@item Instale los paquetes necesarios: LilyPond, Ghostscript e ImageMagick.

@item Cree un usuario nuevo con el nombre de @code{lily}:

@example
adduser lily
@end example

@noindent
Esto también creará un nuevo grupo para el usuario @code{lily}, y una
carpeta personal, @code{/home/lily}

@item En la carpeta personal del usuario @code{lily}, cree un archivo para usarlo como un sistema de archivos separado:

@example
dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
@end example

@noindent
Este ejemplo crea un archivo de 200MB para su uso como el sistema de
archivos de la jaula.

@item Cree un dispositivo loop, haga un sistema de archivos y móntelo,
después cree una carpeta que sea escribible por el usuario
@code{lily}:

@example
mkdir /mnt/lilyloop
losetup /dev/loop0 /home/lily/loopfile
mkfs -t ext3 /dev/loop0 200000
mount -t ext3 /dev/loop0 /mnt/lilyloop
mkdir /mnt/lilyloop/lilyhome
chown lily /mnt/lilyloop/lilyhome
@end example

@item En la configuración de los servidores, JAIL será @code{/mnt/lilyloop}
y DIR será @code{/lilyhome}.

@item Cree un gran árbol de directorios dentro de la jaula copiando los
archivos necesarios, como se muestra en el guión de ejemplo que aparece
más abajo.

Puede usar @code{sed} para crear los archivos de copia necesarios para
un ejecutable dado:

@example
for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/;  \
  do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\&  \
    cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p  \
      \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done
@end example

@end itemize

@subheading Guión de ejemplo para Ubuntu 8.04 de 32 bits

@example
#!/bin/sh
## aquí se fijan los valores predeterminados

username=lily
home=/home
loopdevice=/dev/loop0
jaildir=/mnt/lilyloop
# prefijo (¡sin la barra inicial!)
lilyprefix=usr/local
# el directorio en que lilypond se encuentra instalado en el sistema
lilydir=/$lilyprefix/lilypond/

userhome=$home/$username
loopfile=$userhome/loopfile
adduser $username
dd if=/dev/zero of=$loopfile bs=1k count=200000
mkdir $jaildir
losetup $loopdevice $loopfile
mkfs -t ext3 $loopdevice 200000
mount -t ext3 $loopdevice $jaildir
mkdir $jaildir/lilyhome
chown $username $jaildir/lilyhome
cd $jaildir

mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
chmod a+w tmp

cp -r -L $lilydir $lilyprefix
cp -L /bin/sh /bin/rm bin
cp -L /usr/bin/convert /usr/bin/gs usr/bin
cp -L /usr/share/fonts/truetype usr/share/fonts

# Ahora la magia de copiar las bibliotecas
for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh"  \
  "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=>  \
    \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed  \
      's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/'  \
        | sed '/.*=>.*/d'; done | sh -s

# Los archivos compartidos para ghostscript...
      cp -L -r /usr/share/ghostscript usr/share
# Los archivos compartidos para ImageMagick
      cp -L -r /usr/lib/ImageMagick* usr/lib

### Ahora, suponiendo que tenemos test.ly en /mnt/lilyloop/lilyhome,
### deberíamos poder ejecutar:
### Observe que /$lilyprefix/bin/lilypond es un guión, que establece
### un valor para LD_LIBRARY_PATH : esto es crucial
      /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
@end example

@c " keep quote signs balanced for context-sensitive editors

@node Mensajes de error
@section Mensajes de error
@translationof Error messages

@cindex error, mensajes de
@cindex mensajes de error

Pueden aparecer distintos mensajes de error al compilar un archivo:

@table @emph

@item Advertencia
@cindex advertencia
Algo tiene un aspecto sospechoso.  Si estamos pidiendo algo fuera de
lo común, entenderemos el mensaje y podremos ignorarlo.  Sin embargo,
las advertencias suelen indicar que algo va mal con el archivo de
entrada.

@item Error
@cindex error
Algo va claramente mal.  El paso actual de procesamiento (análisis,
interpretación o formateo visual) se dará por terminado, pero el
siguiente paso se saltará.

@item Error fatal
@cindex error fatal
@cindex fatal, error
Algo va claramente mal, y LilyPond no puede seguir.  Rara vez sucede
esto.  La causa más frecuente son las tipografías mal instaladas.

@item Error de Scheme
@cindex traza de Scheme
@cindex llamadas, traza de
@cindex Scheme, error de
@cindex error de Scheme
Los errores que ocurren al ejecutar código de Scheme se interceptan
por parte del intérprete de Scheme.  Si se está ejecutando con las
opciones @option{-V} o @option{--verbose} (prolijo) entonces se imprime
una traza de llamadas de la función ofensiva.

@item Error de programación
@cindex error de programación
@cindex programación, error de
Ha habido algún tipo de inconsistencia interna.  Estos mensajes de
error están orientados a ayudar a los programadores y a los
depuradores.  Normalmente se pueden ignorar.  En ocasiones aparecen en
cantidades tan grandes que pueden entorpecer la visión de otros
mensajes de salida.

@item Abortado (volcado de core)
Esto señala un error de programación serio que ha causado la
interrupción abrupta del programa.  Estos errores se consideran
críticos.  Si se topa con uno, envíe un informe de fallo.
@end table

@cindex error, formato de los mensajes de

Si los errores y advertencias se pueden ligar a un punto del archivo
de entrada, los mensajes tienen la forma siguiente:

@example
@var{archivo}:@var{línea}:@var{columna}: @var{mensaje}
@var{línea de entrada problemática}
@end example

Se inserta un salto de línea en la línea problemática para indicar la
columna en que se encontró el error. Por ejemplo,

@example
prueba.ly:2:19: error: no es una duración: 5
  @{ c'4 e'
           5 g' @}
@end example

Estas posiciones son la mejor suposición de LilyPond sobre dónde se ha
producido el mensaje de error, pero (por su propia naturaleza) las
advertencias y errores se producen cuando ocurre algo inesperado.  Si
no ve un error en la línea que se indica del archivo de entrada, trate
de comprobar una o dos líneas por encima de la posición indicada.

Observe que los diagnósticos se pueden activar en cualquier punto
durante las numerosas fases del procesado.  Por ejemplo, si hay
partes de la entrada que se procesan varias veces (como en la
salida midi y de disposición de la página), o si la misma variable
musical se utiliza en más de un contexto, puede aparecer el mismo
mensaje varias veces.  Los diagnósticos producidos en un estado
@q{tardío} (como las comprobaciones de compás) también podrían
emitirse más de una vez.

Se ofrece más información sobre los errores en la sección @ref{Errores
comunes}.


@node Errores comunes
@section Errores comunes
@translationof Common errors

Las condiciones de error que se describen más abajo se producen con
frecuencia, aunque su causa no es obvia o fácil de encontrar.  Una vez
se han visto y comprendido, se manejan sin problema.


@menu
* La música se sale de la página::
* Aparece un pentagrama de más::
* Mensaje de error Unbound variable %::
* Mensaje de error FT_Get_Glyph_Name::
* Advertencia sobre que las afinidades del pentagrama sólo deben decrecer::
* Mensaje de error Unexpected new::
* Advertencia de que una voz requiere ajustes voiceXx o shiftXx::
@end menu

@node La música se sale de la página
@unnumberedsubsec La música se sale de la página
@translationof Music runs off the page

La música que se sale de la página por el margen derecho o que aparece
exageradamente comprimida está causada casi siempre por haber
introducido una duración incorrecta para una nota, produciendo que la
nota final de un compás se extienda más allá de la línea divisoria.
Esto no es inválido si la nota final de un compás no termina sobre la
línea divisoria introducida automáticamente, pues simplemente se
supone que la nota se solapa encima del siguiente compás.  Pero si se
produce una larga secuencia tales notas solapadas, la música puede
aparecer comprimida o salirse de la página porque los saltos de línea
automáticos solamente se pueden insertar al final de compases
completos, es decir, aquellos en que todas las notas terminan antes de
o justo al final del compás.

@warning{Una duración incorrecta puede hacer que se inhiban los saltos
de línea, lo que llevaría a una sola línea de música muy comprimida o
que se salga de la página.}

La duración incorrecta se puede encontrar fácilmente si se utilizan
comprobaciones de compás, véase @ruser{Comprobación de compás y de
número de compás}.

Si realmente queremos tener una serie de estos compases con notas
solapadas, debemos insertar una línea divisoria invisible donde
queramos el salto de línea.  Para ver más detalles, consulte
@ruser{Barras de compás}.


@node Aparece un pentagrama de más
@unnumberedsubsec Aparece un pentagrama de más
@translationof An extra staff appears

Si no se crean los contextos explícitamente con @code{\new} o con
@code{\context}, se crearán discretamente tan pronto como se encuentra
una instrucción que no se puede aplicar a un contexto existente.  En
partituras sencillas, la creación automática de los contextos es útil,
y casi todos los ejemplos de los manuales de LilyPond se aprovechan de
esta simplificación.  Pero ocasionalmente la creación discreta de
contextos puede hacer aflorar pentagramas o partituras nuevos e
inesperados.  Por ejemplo, podría esperarse que el código siguiente
hiciera que todas las notas dentro del pentagrama siguiente estuvieran
coloreadas de rojo, pero de hecho el resultado son dos pentagramas,
permaneciendo el de abajo con las notas en el color negro
predeterminado.

@lilypond[quote,verbatim,fragment]
\override Staff.NoteHead.color = #red
\new Staff { a' }
@end lilypond

Esto es así porque no existe ningún contexto @code{Staff} cuando se
procesa la instrucción override de sobreescritura, se crea uno
implícitamente y la sobreescritura se aplica a éste, pero entonces la
instrucción @code{\new Staff} crea un pentagrama nuevo y distinto, en
el que se colocan las notas.  El código correcto para colorear todas
las notas de rojo es

@lilypond[quote,verbatim]
\new Staff {
  \override Staff.NoteHead.color = #red
  a'
}
@end lilypond

@node Mensaje de error Unbound variable %
@unnumberedsubsec Mensaje de error Unbound variable %
@translationof Error message Unbound variable %

Este mensaje de error aparece al final de los mensajes de la consola o
del archivo de registro junto a un mensaje @qq{GUILE señaló un error
@dots{}} cada vez que se llame a una rutina de Scheme que
(incorrectamente) contenga un comentario @emph{de LilyPond} en lugar
de un comentario @emph{de Scheme}.

Los comentarios de LilyPond comienzan con un símbolo de porcentaje,
(@code{%}), y no se deben utilizar dentro de las rutinas de Scheme.
Los comentarios de Scheme comienzan con punto y coma, (@code{;}).

@node Mensaje de error FT_Get_Glyph_Name
@unnumberedsubsec Mensaje de error FT_Get_Glyph_Name
@translationof Error message FT_Get_Glyph_Name

Este mensaje de error aparece en la salida de la consola o en el
archivo log de registro si un archivo de entrada contiene un carácter
que no es ASCII y no se ha guardado en la codificación de caracteres
UTF-8.  Para ver más detalles, consulte @ruser{Codificación del
texto}.


@node Advertencia sobre que las afinidades del pentagrama sólo deben decrecer
@unnumberedsubsec Advertencia sobre que las afinidades del pentagrama sólo deben decrecer
@translationof Warning staff affinities should only decrease

Esta advertencia puede aparecer si no hay ningún pentagrama en la
salida impresa, por ejemplo si sólo hay un contexto @code{ChordName} y
un contexto @code{Lyrics} como en una hoja guía de acordes.  Los
mensajes de advertencia se pueden evitar haciendo que uno de los
contextos se comporte como un pentagrama, insertando

@example
\override VerticalAxisGroup.staff-affinity = ##f
@end example

@noindent
al comienzo.  Para ver más detalles, consulte @qq{Espaciado de las
líneas que no son pautas} en @ruser{Espaciado vertical flexible dentro
de los sistemas}.


@node Mensaje de error Unexpected new
@unnumberedsubsec Mensaje de error Unexpected @code{@bs{}new}
@translationof Error message unexpected new

Un bloque @code{\score} debe contener una @emph{única} expresión
musical.  Si en vez de ello contiene varias instrucciones
@code{\new Staff}, @code{\new StaffGroup} o contextos similares
introducidos con @code{\new} sin que se hayan encerrado entre
llaves curvas, @code{@{ @dots{} @}}, o dobles paréntesis en
ángulo, @code{<< @dots{}  >>}, así:

@example
\score @{
  % Invalid! Generates error: syntax error, unexpected \new
  \new Staff @{ @dots{} @}
  \new Staff @{ @dots{} @}
@}
@end example

@noindent
entonces se producirá el mensaje de error.

Para evitar el error, encierre todas las instrucciones @code{\new}
dentro de llaves curvas o dobles paréntesis en ángulo.

El uso de llaves curvas introduce las instrucciones @code{\new} de
forma secuencial:

@lilypond[quote,verbatim]
\score {
  {
    \new Staff { a' a' a' a' }
    \new Staff { g' g' g' g' }
  }
}
@end lilypond

@noindent
pero es más probable que se encuentre utilizando dobles ángulos de
manera que los pentagramas nuevos se inserten en paralelo, es
decir, simultáneamente:

@lilypond[quote,verbatim]
\score {
  <<
    \new Staff { a' a' a' a' }
    \new Staff { g' g' g' g' }
  >>
}
@end lilypond

@node Advertencia de que una voz requiere ajustes voiceXx o shiftXx
@unnumberedsubsec Advertencia de que una voz requiere ajustes @code{@bs{}voiceXx} o @code{@bs{}shiftXx}
@translationof Warning this voice needs a voiceXx or shiftXx setting

Si acontecen dos notas de distintas voces son plicas en la misma
dirección y en el mismo momento musical, pero las voces no tienen
especificado ningún desplazamiento de voz específico, aparece el
mensaje @samp{advertencia: esta voz requiere ajustes \voiceXx o
\shiftXx} cuando se compila el archivo de LilyPond.  La
advertencia aparece incluso si las notas no tienen plicas
visibres, por ejemplo redondas, si las plicas de figuras más
breves que tuviesen las misma altura, estuvieran en la misma
dirección.

Recuerde que la dirección de la plica depende de la posición de la
nota sobre el pentagrama a no ser que la dirección de la plica
venga especificada, por ejemplo mediante @code{\voiceOne}.  En
este caso, la advertencia aparece solamente cuando las plicas
están en la misma dirección, es decir, cuando se encuentran en la
misma mitad del pentagrama.

Situando las notas en voces que tengan direcciones de plica y
desplazamientos especificados, por ejemplo usando @code{\voiceOne}
y otras instrucciones, se pueden evitar estos mensajes.

Las notas que están en voces con numeración más alta,
@code{\voiceThree} y siguientes, se desplazan automáticamente para
evitar las colisiones entre columnas.  Esto produce un
desplazamient que es visible en las notas con plica, pero las
redondas no se desplazan de forma visible a no ser que se produzca
una verdadera colisión, o si las voces se cruzan respecto a su
orden natural (cuando una voz con @code{\voiceThree} es más aguda
que otra con @code{\voiceOne}, y casos semejantes).

@seealso
@rlearning{Voces explícitas},
@rlearning{Ejemplos reales de música},
@ruser{Polifonía en un solo pentagrama},
@ruser{Resolución de las colisiones}.