Doc-es: update Usage.

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

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

@ignore
    Translation of GIT committish: 4b2f03141029b4bd73bee4d6175f727d92390076

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


@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
deberían consultar también el apartado @ref{Configuración para 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::
@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}.


@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 -e,--evaluate=@var{expresión}
Evaluar la @var{expresión} de Scheme antes de analizar los archivos
@file{.ly}.  Se pueden pasar varias opciones @code{-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 @code{.ly}.

@item -f,--format=@var{formato}
Formato de la salida.  Como @code{formato} se puede elegir entre
@code{ps}, @code{pdf} y @code{png}.

Ejemplo: @code{lilypond -fpng @var{archivo}.ly}

@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

A continuación veremos algunas opciones interesantes.

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

@table @samp
@item help
La ejecución de @code{lilypond -dhelp} imprimirá todas las opciones
@code{-d} que están 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 @code{.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
@code{--safe} (seguro) o @code{--jail} (jaula).  La opción
@code{--safe} evita que el código de Scheme en línea arme un desastre,
por ejemplo

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

La opción @code{-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.

@code{-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 @code{--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
 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

 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 @code{-dno-print-pages}.
@end table

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

@item preview
Generar un archivo de salida que contenga solamente los títulos de
cabecera y el primer sistema de la primera página.

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

@end table



@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 --include, -I=@var{directorio}
Añadir el @var{directorio} a la ruta de búsqueda de archivos de
entrada.
@cindex archivos, búsqueda de
@cindex búsqueda, ruta de

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

@item -o,--output=@var{ARCHIVO}
Establecer el nombre del archivo de salida predeterminado a
@var{ARCHIVO}.  Se añade el sufijo correspondiente (por ejemplo,
@code{.pdf} para PDF).

@item --ps
Generar PostScript.

@item --png
Generar imágenes de las páginas en formato PNG.  Esto implica
@code{--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

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



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

La opción @code{--jail} (jaula) proporciona una alternativa más
flexible a la opción @code{--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 @code{--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
@code{--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 -t}), y, si su sistema operativo
lo contempla, el tamaño de la memoria que se puede reservar.
@end table


@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_GC_YIELD
Con esta variable se puede ajustar la huella y el desempeño de
memoria.  Es un 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 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 @code{-V} o @code{--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

Se 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::
@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}, 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' { c d e f }
}
@end lilypond

La forma correcta es invertir el orden de las instrucciones
@code{\repeat} y @code{\relative}, así:

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


@node Error aparente en ../ly/init.ly
@unnumberedsubsubsec 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 @code{../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 @ref{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{Explicación de 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 %
@unnumberedsubsubsec 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
...} 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}.