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

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

@ignore
    Translation of GIT committish: f3768208f242fbf03bb49d185dfa3db4c0fb46f7

    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.15.18"


@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 la 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
producirá como salida @var{base}@file{-violin.pdf} y
@var{base}@file{-cello-1.pdf}.


@unnumberedsubsubsec Instrucciones estándar de la línea de órdenes

Si su terminal (o ventana de órdenes) contempla las redirecciones
normales, quizá le sean de utilidad las siguientes instrucciones para
redirigir la salida de la consola a un archivo:

@itemize

@item
@code{lilypond archivo.ly 1>salidaestandar.log} para redirigir la salida normal

@item
@code{lilypond archivo.ly 2>salidadeerror.log} para redirigir los mensajes de error

@item
@code{lilypond archivo.ly &>todo.log} para redirigir toda la salida

@end itemize

Consulte la documentación de su shell para ver si contempla estas
opciones, o si la sintaxis es distinta.  Observe que son instrucciones
del shell y que no tienen nada que ver con lilypond.

@node Opciones de la línea de órdenes para lilypond
@unnumberedsubsec Opciones de la línea de órdenes para @command{lilypond}
@translationof Command line options for lilypond

@cindex invocación de @command{lilypond}
@cindex opciones de la línea de órdenes para @command{lilypond}
@cindex línea de órdenes, opciones de
@cindex modificadores

Están contempladas las siguientes opciones:

@table @code

@item -d,--define-default=@var{variable}=@var{valor}
Establece la opción interna del programa @var{variable} al valor de
Scheme @var{valor}.  Si no se proporciona ningún @var{valor}, se usa
@var{#t}.  Para desactivar una opción se puede anteponer @code{no-} a
la @var{variable}, p.ej.:

@cindex apuntar y pulsar, línea de órdenes

@example
-dno-point-and-click
@end example

@noindent
es lo mismo que
@example
-dpoint-and-click=#f
@end example

Están contempladas las siguientes opciones:

@cindex help (ayuda), línea de órdenes

@table @code

@item help
La ejecución de @code{lilypond -dhelp} imprime todas las opciones
@option{-d} disponibles.

@cindex paper-size, línea de órdenes

@item paper-size
Esta opción establece el tamaño predeterminado del papel,
@example
-dpaper-size=\"letter\"
@end example

@noindent
Observe que la cadena se debe incluir dentro de comillas escapadas
( @code{\"} ).

@c Match " in previous line to help context-sensitive editors

@cindex safe, línea de órdenes

@item safe
No confiar en la entrada @file{.ly}.

Cuando el proceso de tipografía de LilyPond se encuentra disponible a
través de un servidor web, @b{SE DEBEN} pasar las opciones
@option{--safe} (seguro) o @option{--jail} (jaula).  La opción
@option{--safe} evita que el código de Scheme en línea arme un desastre,
por ejemplo

@quotation
@verbatim
#(system "rm -rf /")
{
  c4^$(ly:gulp-file "/etc/passwd")
}
@end verbatim
@end quotation

La opción @option{-dsafe} funciona evaluando las expresiones en línea de
Scheme dentro de un módulo especial seguro.  Este módulo seguro deriva
del módulo GUILE @file{safe-r5rs}, pero añade ciertas funciones del
API de LilyPond.  Estas funciones se relacionan en
@file{scm/safe-lily.scm}.

Además, el modo seguro prohíbe las directivas @code{\include} e
inhabilita el uso de barras invertidas en las cadenas de @TeX{}.

En el modo seguro, no es posible la importación de variables de
LilyPond dentro de Scheme.

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

El modo seguro impide que muchos fragmentos útiles de código de
LilyPond se puedan compilar.  La opción @option{--jail} es una
alternativa más segura, pero su preparación requiere más trabajo.

@cindex salida, establecer el formato de

@item backend
el formato de salida que usar para el back-end o extremo final.
Para el @code{formato} se puede elegir entre

@table @code
@item ps

@cindex PostScript, salida

para PostScript.

Los archivos PostScript incluyen las tipografías TTF, Type1 y OTF.  No
se seleccionan subconjuntos de estas tipografías.  Cuando se usan
conjuntos de caracteres orientales, esto puede dar lugar a archivos
enormes.

@item eps

@cindex Postscript encapsulado
@cindex EPS (PostScript Encapsulado)

para obtener PostScript encapsulado.  Esto vuelca cada una de las
páginas/sistemas como un archivo @file{EPS} distinto, sin tipografías,
y como un solo archivo @file{EPS} encuadernado con todas las
páginas/sistemas con las tipografías incluidas.

Este modo se usa de forma predeterminada por parte de
@command{lilypond-book}.

@item svg

@cindex SVG (Gráficos vectoriales escalables)

para obtener SVG (gráficos vectoriales escalables).

Crea un único archivo SVG que contiene toda la salida de música, con
las tipografías incrustadas.  Se necesita un visor de SVG que
contemple las tipografías incrustadas, o un visor de SVG que pueda
sustituir las tipografías incrustadas por tipografías OTF.  Bajo UNIX,
puede usar @uref{http://www.inkscape.org,Inkscape} (versión 0.42 o
posterior), después de copiar las tipografías OTF del directorio de
LilyPond (que normalmente es
@file{/usr/share/lilypond/VERSIÓN/fonts/otf/}) al directorio
@file{~/.fonts/}.

@item scm

@cindex Scheme, volcado de
@cindex salida, volcado de Scheme

 para obtener un volcado de las instrucciones internas de dibujo
basadas en Scheme, en bruto.

@item null
 no producir una salida impresa; tiene el mismo efecto que @option{-dno-print-pages}.

@end table

Ejemplo: @code{lilypond -dbackend=svg @var{archivo}.ly}

@item preview

@cindex vista previa, línea de órdenes

Esta opción está contemplada por todos los back-ends:
@code{pdf}, @code{png}, @code{ps}, @code{eps} y @code{svg},
pero no por @code{scm} y genera un archivo de salida
que contiene solamente los títulos de
cabecera y el primer sistema de música.  Si se usan bloques
@code{\bookpart}, los títulos y el primer sistema de todos los bloques
@code{\bookpart} aparecerán en la salida.

Se genera un archivo adicional en la forma
@code{myFile.preview.extensión}, para evitarlo use las opciones
adicionales @option{-dprint-pages} ó @option{-dno-print-pages}
según sus necesidades.

@item gui
Ejecutar en modo silencioso y redirigir toda la salida a un archivo de
registro.

Nota para usuarios de Windows: de forma predeterminada
@code{lilypond.exe} imprime toda la información del progreso de
ejecución hacia la ventana de la consola, @code{lilypond-windows.exe}
no lo hace y devuelve una indicación del sistema o prompt sin ninguna
información del progreso de la ejecución 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.

@item print-pages
Generar las páginas completas, el ajuste predeterminado.
@option{-dno-print-pages} es útil en combinación con @option{-dpreview}.

@end table

@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}

@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{--safe} cuando el proceso de tipografía de
LilyPond está disponible a través de un servidor web o cuando LilyPond
ejecuta archivos fuente procedentes del exterior.

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 es un asunto algo delicado, pues debemos
asegurarnos de que LilyPond puede encontrar @emph{dentro de la jaula}
todo lo que necesita para poder compilar la fuente.  Una configuración
típica 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 mencionamos, también se
debe ejecutar con privilegios del superusuario (que por supuesto
perderá inmediatamente), posiblemente usando @command{sudo}.  Es buena
idea 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.

@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 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 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.

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::
* Error aparente en ../ly/init.ly::
* Mensaje de error Unbound variable %::
* Mensaje de error FT_Get_Glyph_Name::
* Advertencia sobre que las afinidades del pentagrama sólo deben decrecer::
@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,relative=2]
\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,relative=2]
\new Staff {
  \override Staff.NoteHead #'color = #red
  a
}
@end lilypond

Como segundo ejemplo, si una instrucción @code{\relative} se escribe
dentro de una instrucción @code{\repeat}, el resultado son dos
pentagramas, el segundo desplazado respecto al primero, porque la
instrucción @code{\repeat} genera dos bloques @code{\relative},
cada uno de los cuales crea implícitamente bloques @code{Staff} y
@code{Voice}.

@lilypond[quote,verbatim]
\repeat unfold 2 {
  \relative c' { c4 d e f }
}
@end lilypond

El problema se resuelve instanciando el contexto @code{Voice}
explícitamente:

@lilypond[quote,verbatim]
\new Voice {
  \repeat unfold 2 {
    \relative c' { c4 d e f }
  }
}
@end lilypond


@node Error aparente en ../ly/init.ly
@unnumberedsubsec Error aparente en @code{../ly/init.ly}
@translationof Apparent error in ../ly/init.ly

Pueden aparecer varios mensajes de error extraños acerca de errores de
sintaxis en @file{../ly/init.ly} si el archivo de entrada no está
correctamente formado, por ejemplo si no contiene llaves o comillas
correctamente emparejados.

El error más común es la falta de una llave de cierre, (@code{@}}), al
final de un bloque @code{score}.  Aquí la solución es obvia: compruebe
que el bloque @code{score} está correctamente cerrado.  La estructura
correcta de un archivo de entrada está descrita en @rlearning{Cómo
funcionan los archivos de entrada de LilyPond}.  Usando un editor que
resalte automáticamente las llaves correspondientes es de mucha ayuda
para evitar estos errores.

Una segunda causa frecuente es la falta de un espacio entre la última
sílaba de un bloque lyrics (de letra) y la llave de cierre,
(@code{@}}).  Sin esta separación, se considera que la llave forma
parte de la sílaba.  Siempre se aconseja asegurarse de que hay
espacios antes y después de @emph{todas} las llaves.  Para conocer la
importancia de este asunto al utilizar letras de canciones, consulte
@ruser{Introducir la letra}.

Este mensaje de error también puede aparecer si se omiten las comillas
de terminación (@code{"}).  En este caso, un mensaje de error
adicional debería indicar un número de línea cercano al de aquella
donde está el error.  Las comillas desbalanceadas estarán por lo
general una o dos líneas por encima.


@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}.