1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
4 Translation of GIT committish: e18567dccce0f16b680e6b7e562329e5f8bcae59
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
14 @node Ejecutar LilyPond
15 @chapter Ejecutar LilyPond
16 @translationof Running LilyPond
18 Este capítulo detalla los aspectos técnicos de la ejecución de
22 * Utilización normal::
23 * Utilización desde la línea de órdenes::
29 @node Utilización normal
30 @section Utilización normal
31 @translationof Normal usage
33 Casi todos los usuarios ejecutan LilyPond por medio de un interfaz
34 gráfico; consulte @rlearning{Primeros pasos} si no lo ha leído aún.
37 @node Utilización desde la línea de órdenes
38 @section Utilización desde la línea de órdenes
39 @translationof Command-line usage
41 Esta sección contiene información adicional sobre el uso de LilyPond
42 en la línea de órdenes. Esta forma puede ser preferible para pasarle
43 al programa algunas opciones adicionales. Además, existen algunos
44 programas complementarios @q{de apoyo} (como @code{midi2ly}) que sólo
45 están disponibles en la línea de órdenes.
47 Al hablar de la @q{línea de órdenes}, nos referimos a la consola del
48 sistema operativo. Los usuarios de Windows posiblemente estén más
49 familiarizados con los términos @q{ventana de MS-DOS} o @q{línea de
50 comandos}; Los usuarios de MacOS@tie{}X puede que estén más
51 familiarizados con los términos @q{terminal} o @q{consola}. Éstos
52 deberían consultar también el apartado @ref{Configuración para MacOS X}.
54 La descripción del uso de esta parte de los sistemas operativos se
55 sale del ámbito de este manual; le rogamos que consulte otros
56 documentos sobre este tema si no le resulta familiar la línea de
60 * Invocar a LilyPond::
61 * Opciones de la línea de órdenes para lilypond::
62 * Variables de entorno::
65 @node Invocar a LilyPond
66 @unnumberedsubsec Invocar @command{lilypond}
67 @translationof Invoking lilypond
69 El ejecutable @command{lilypond} se puede llamar desde la línea de
70 órdenes de la siguiente manera:
73 lilypond [@var{opción}]@dots{} @var{archivo}@dots{}
76 Cuando se invoca con un nombre de archivo sin extensión, se prueba en
77 primer lugar con la extensión @file{.ly}. Para leer la entrada desde
78 stdin, utilice un guión (@code{-}) en sustitución de @var{archivo}.
80 Cuando se procesa @file{archivo.ly}, la salida resultante son los
81 archivos @file{archivo.ps} y @file{archivo.pdf}. Se pueden
82 especificar varios archivos; cada uno de ellos se procesará de forma
83 independiente@footnote{El estado de GUILE no se restablece después de
84 procesar un archivo @code{.ly}, por lo que debe tener cuidado de no
85 modificar ningún valor predeterminado desde dentro de Scheme.}.
87 Si @file{archivo.ly} contiene más de un bloque @code{\score}, el resto
88 de las partituras se obtendrán como salida en archivos numerados,
89 empezando por @file{archivo-1.pdf}. además, el valor de
90 @code{output-suffix} (sufijo de salida) se insertará entre el nombre
91 base y el número. Un archivo de entrada que contenga
94 #(define output-suffix "violin")
96 #(define output-suffix "cello")
101 producirá como salida @var{base}@file{-violin.pdf} y
102 @var{base}@file{-cello-1.pdf}.
105 @node Opciones de la línea de órdenes para lilypond
106 @unnumberedsubsec Opciones de la línea de órdenes para @command{lilypond}
107 @translationof Command line options for lilypond
109 @cindex invocación de @command{lilypond}
110 @cindex opciones de la línea de órdenes para @command{lilypond}
111 @cindex línea de órdenes, opciones de
112 @cindex modificadores
114 Están contempladas las siguientes opciones:
118 @item -e,--evaluate=@var{expresión}
119 Evaluar la @var{expresión} de Scheme antes de analizar los archivos
120 @file{.ly}. Se pueden pasar varias opciones @code{-e}, que se
121 evaluarán en secuencia.
123 La expresión se evaluará en el módulo @code{guile-user}, de manera que
124 si quiere usar definiciones dentro de @var{expresión}, debe utilizar
127 lilypond -e '(define-public a 42)'
131 en la línea de órdenes, e incluir
134 #(use-modules (guile-user))
138 al principio del archivo @code{.ly}.
140 @item -f,--format=@var{formato}
141 Formato de la salida. Como @code{formato} se puede elegir entre
142 @code{ps}, @code{pdf} y @code{png}.
144 Ejemplo: @code{lilypond -fpng @var{archivo}.ly}
146 @item -d,--define-default=@var{variable}=@var{valor}
147 Establece la opción interna del programa @var{variable} al valor de
148 Scheme @var{valor}. Si no se proporciona ningún @var{valor}, se usa
149 @var{#t}. Para desactivar una opción se puede anteponer @code{no-} a
150 la @var{variable}, p.ej.:
152 @cindex apuntar y pulsar, línea de órdenes
161 -dpoint-and-click='#f'
164 A continuación veremos algunas opciones interesantes.
166 @cindex help (ayuda), línea de órdenes
170 La ejecución de @code{lilypond -dhelp} imprimirá todas las opciones
171 @code{-d} que están disponibles.
173 @cindex paper-size, línea de órdenes
176 Esta opción establece el tamaño predeterminado del papel,
178 -dpaper-size=\"letter\"
182 Observe que la cadena se debe incluir dentro de comillas escapadas
185 @c Match " in previous line to help context-sensitive editors
187 @cindex safe, línea de órdenes
190 No confiar en la entrada @code{.ly}.
192 Cuando el proceso de tipografía de LilyPond se encuentra disponible a
193 través de un servidor web, @b{SE DEBEN} pasar las opciones
194 @code{--safe} (seguro) o @code{--jail} (jaula). La opción
195 @code{--safe} evita que el código de Scheme en línea arme un desastre,
202 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
207 La opción @code{-dsafe} funciona evaluando las expresiones en línea de
208 Scheme dentro de un módulo especial seguro. Este módulo seguro deriva
209 del módulo GUILE @file{safe-r5rs}, pero añade ciertas funciones del
210 API de LilyPond. Estas funciones se relacionan en
211 @file{scm/@/safe@/-lily@/.scm}.
213 Además, el modo seguro prohíbe las directivas @code{\include} e
214 inhabilita el uso de barras invertidas en las cadenas de @TeX{}.
216 En el modo seguro, no es posible la importación de variables de
217 LilyPond dentro de Scheme.
219 @code{-dsafe} @emph{no} detecta la sobreutilización de recursos. Aún
220 es posible hacer que el programa se cuelgue indefinidamente, por
221 ejemplo alimentando el backend con estructuras de datos cíclicas. Por
222 tanto, si se está utilizando LilyPond sobre un servidor web accesible
223 públicamente, el proceso debe limitarse tanto en el uso de CPU como de
226 El modo seguro impide que muchos fragmentos útiles de código de
227 LilyPond se puedan compilar. La opción @code{--jail} es una
228 alternativa más segura, pero su preparación requiere más trabajo.
230 @cindex salida, establecer el formato de
232 el formato de salida que usar para el back-end o extremo final.
233 Para el @code{formato} se puede elegir entre
236 @cindex PostScript, salida
239 Los archivos PostScript incluyen las tipografías TTF, Type1 y OTF. No
240 se seleccionan subconjuntos de estas tipografías. Cuando se usan
241 conjuntos de caracteres orientales, esto puede dar lugar a archivos
245 para obtener PostScript encapsulado. Esto vuelca cada una de las
246 páginas/sistemas como un archivo @file{EPS} distinto, sin tipografías,
247 y como un solo archivo @file{EPS} encuadernado con todas las
248 páginas/sistemas con las tipografías incluidas.
250 Este modo se usa de forma predeterminada por parte de
251 @command{lilypond-book}.
255 @cindex SVG (Gráficos vectoriales escalables)
257 para obtener SVG (gráficos vectoriales escalables).
259 Crea un único archivo SVG que contiene toda la salida de música, con
260 las tipografías incrustadas. Se necesita un visor de SVG que
261 contemple las tipografías incrustadas, o un visor de SVG que pueda
262 sustituir las tipografías incrustadas por tipografías OTF. Bajo UNIX,
263 puede usar @uref{http://www.inkscape.org,Inkscape} (versión 0.42 o
264 posterior), después de copiar las tipografías OTF del directorio de
265 LilyPond (que normalmente es
266 @file{/usr/share/lilypond/VERSIÓN/fonts/otf/}) al directorio
271 @cindex Scheme, volcado de
273 para obtener un volcado de las instrucciones internas de dibujo
274 basadas en Scheme, en bruto.
277 no producir una salida impresa; tiene el mismo efecto que @code{-dno-print-pages}.
280 Ejemplo: @code{lilypond -dbackend=svg @var{archivo}.ly}
283 @cindex vista previa, línea de órdenes
284 Generar un archivo de salida que contenga solamente los títulos de
285 cabecera y el primer sistema de música. Si se usan bloques
286 @code{\bookpart}, los títulos y el primer sistema de todos los bloques
287 @code{\bookpart} aparecerán en la salida. Los motores @code{ps},
288 @code{eps} y @code{svg} contemplan esta opción.
291 Generar las páginas completas, el ajuste predeterminado.
292 @code{-dno-print-pages} es útil en combinación con @code{-dpreview}.
299 Mostrar un resumen de las formas de utilización.
301 @item -H,--header=@var{CAMPO}
302 Volcar un campo de cabecera al archivo @file{NOMBREBASE.@var{CAMPO}}
304 @item --include, -I=@var{directorio}
305 Añadir el @var{directorio} a la ruta de búsqueda de archivos de
307 @cindex archivos, búsqueda de
308 @cindex búsqueda, ruta de
310 @item -i,--init=@var{archivo}
311 Establecer el archivo de inicio a @var{archivo} (predeterminado:
314 @item -o,--output=@var{ARCHIVO}
315 Establecer el nombre del archivo de salida predeterminado a
316 @var{ARCHIVO}. Se añade el sufijo correspondiente (por ejemplo,
317 @code{.pdf} para PDF).
323 Generar imágenes de las páginas en formato PNG. Esto implica
324 @code{--ps}. La resolución en PPP de la imagen se puede establecer
330 @cindex PDF (formato de documento portátil), salida de
333 Generar PDF. Implica @code{--ps}.
337 @item -j,--jail=@var{usuario},@var{grupo},@var{jaula},@var{directorio}
338 Ejecutar @command{lilypond} en una jaula de chroot.
340 La opción @code{--jail} (jaula) proporciona una alternativa más
341 flexible a la opción @code{--safe} cuando el proceso de tipografía de
342 LilyPond está disponible a través de un servidor web o cuando LilyPond
343 ejecuta archivos fuente procedentes del exterior.
345 La opción @code{--jail} funciona cambiando la raíz de
346 @command{lilypond} a @var{jaula} justo antes de comenzar el proceso de
347 compilación en sí. Entonces se cambian el usuario y el grupo a los
348 que se han dado en la opción, y el directorio actual se cambia a
349 @var{directorio}. Esta instalación garantiza que no es posible, al
350 menos en teoría, escapar de la jaula. Observe que para que funcione
351 @code{--jail} se debe ejecutar @command{lilypond} como root, lo que
352 normalmente se puede hacer de una forma segura utilizando
355 La instalación de una jaula es un asunto algo delicado, pues debemos
356 asegurarnos de que LilyPond puede encontrar @emph{dentro de la jaula}
357 todo lo que necesita para poder compilar la fuente. Una configuración
358 típica consta de los siguientes elementos:
361 @item Preparar un sistema de archivos separado
362 Se debe crear un sistema de archivos separado para LilyPond, de forma
363 que se pueda montar con opciones seguras como @code{noexec},
364 @code{nodev} y @code{nosuid}. De esta forma, es imposible ejecutar
365 programas o escribir directamente a un dispositivo desde LilyPond. Si
366 no quiere crear una partición separada, tan sólo tiene que crear un
367 archivo de un tamaño razonable y usarlo para montar un dispositivo
368 loop. El sistema de archivos separado garantiza también que LilyPond
369 nunca pueda escribir en un espacio mayor del que se le permita.
371 @item Preparar un usuario separado
372 Se debe usar un usuario y grupo separados (digamos
373 @code{lily}/@code{lily}) con bajos privilegios para ejecutar LilyPond
374 dentro de la jaula. Debería existir un solo directorio con permisos
375 de escritura para este usuario, y debe pasarse en el valor
378 @item Preparar la jaula
379 LilyPond necesita leer algunos archivos mientras se ejecuta. Todos
380 estos archivos se deben copiar dentro de la jaula, bajo la misma ruta
381 en que aparecen en el sistema de archivos real de root. Todo el
382 contenido de la instalación de LilyPond (por ejemplo
383 @file{/usr/share/lilypond}) se debe copiar.
385 Si surgen problemas, la forma más sencilla de rastrearlos es ejecutar
386 LilyPond usando @command{strace}, lo que le permitirá determinar qué
389 @item Ejecutar LilyPond
390 Dentro de una jaula montada con @code{noexec} es imposible ejecutar
391 ningún programa externo. Por tanto, LilyPond se debe ejecutar con un
392 backend que no necesite tal programa. Como ya mencionamos, también se
393 debe ejecutar con privilegios del superusuario (que por supuesto
394 perderá inmediatamente), posiblemente usando @command{sudo}. Es buena
395 idea limitar el número de segundos de tiempo de CPU que LilyPond puede
396 usar (p.ej., usando @command{ulimit -t}), y, si su sistema operativo
397 lo contempla, el tamaño de la memoria que se puede reservar.
402 Mostrar la información de la versión.
405 Ser prolijo: mostrar las rutas completas de todos los archivos que se
406 leen, y dar información cronométrica.
409 Mostrar la garantía con que viene GNU LilyPond (¡no viene con
410 @strong{NINGUNA GARANTÍA}!).
413 @node Variables de entorno
414 @unnumberedsubsec Variables de entorno
415 @translationof Environment variables
419 @cindex LILYPOND_DATADIR
421 @command{lilypond} reconoce las siguientes variables de entorno:
423 @item LILYPOND_DATADIR
424 Especifica un directorio en el que los mensajes de localización y de
425 datos se buscarán de forma predeterminada. El directorio debe
426 contener subdirectorios llamados @file{ly/}, @file{ps/}, @file{tex/},
430 Selecciona el idioma de los mensajes de advertencia.
432 @item LILYPOND_GC_YIELD
433 Con esta variable se puede ajustar la huella y el desempeño de
434 memoria. Es un porcentaje que ajusta el comportamiento de la
435 administración de memoria. Con valores más altos, el programa usa más
436 memoria; con valores más bajos, usa más tiempo de CPU. El valor
437 predeterminado es @code{70}.
442 @node Mensajes de error
443 @section Mensajes de error
444 @translationof Error messages
446 @cindex error, mensajes de
447 @cindex mensajes de error
449 Pueden aparecer distintos mensajes de error al compilar un archivo:
455 Algo tiene un aspecto sospechoso. Si estamos pidiendo algo fuera de
456 lo común, entenderemos el mensaje y podremos ignorarlo. Sin embargo,
457 las advertencias suelen indicar que algo va mal con el archivo de
462 Algo va claramente mal. El paso actual de procesamiento (análisis,
463 interpretación o formateo visual) se dará por terminado, pero el
464 siguiente paso se saltará.
469 Algo va claramente mal, y LilyPond no puede seguir. Rara vez sucede
470 esto. La causa más frecuente son las tipografías mal instaladas.
472 @item Error de Scheme
473 @cindex traza de Scheme
474 @cindex llamadas, traza de
475 @cindex Scheme, error de
476 @cindex error de Scheme
477 Los errores que ocurren al ejecutar código de Scheme se interceptan
478 por parte del intérprete de Scheme. Si se está ejecutando con las
479 opciones @code{-V} o @code{--verbose} (prolijo) entonces se imprime
480 una traza de llamadas de la función ofensiva.
482 @item Error de programación
483 @cindex error de programación
484 @cindex programación, error de
485 Ha habido algún tipo de inconsistencia interna. Estos mensajes de
486 error están orientados a ayudar a los programadores y a los
487 depuradores. Normalmente se pueden ignorar. En ocasiones aparecen en
488 cantidades tan grandes que pueden entorpecer la visión de otros
491 @item Abortado (volcado de core)
492 Esto señala un error de programación serio que ha causado la
493 interrupción abrupta del programa. Estos errores se consideran
494 críticos. Si se topa con uno, envíe un informe de fallo.
497 @cindex error, formato de los mensajes de
499 Se los errores y advertencias se pueden ligar a un punto del archivo
500 de entrada, los mensajes tienen la forma siguiente:
503 @var{archivo}:@var{línea}:@var{columna}: @var{mensaje}
504 @var{línea de entrada problemática}
507 Se inserta un salto de línea en la línea problemática para indicar la
508 columna en que se encontró el error. Por ejemplo,
511 prueba.ly:2:19: error: no es una duración: 5
516 Estas posiciones son la mejor suposición de LilyPond sobre dónde se ha
517 producido el mensaje de error, pero (por su propia naturaleza) las
518 advertencias y errores se producen cuando ocurre algo inesperado. Si
519 no ve un error en la línea que se indica del archivo de entrada, trate
520 de comprobar una o dos líneas por encima de la posición indicada.
522 Se ofrece más información sobre los errores en la sección @ref{Errores
525 @node Errores comunes
526 @section Errores comunes
527 @translationof Common errors
529 Las condiciones de error que se describen más abajo se producen con
530 frecuencia, aunque su causa no es obvia o fácil de encontrar. Una vez
531 se han visto y comprendido, se manejan sin problema.
535 * La música se sale de la página::
536 * Aparece un pentagrama de más::
537 * Error aparente en ../ly/init.ly::
538 * Mensaje de error Unbound variable %::
539 * Mensaje de error FT_Get_Glyph_Name::
542 @node La música se sale de la página
543 @unnumberedsubsec La música se sale de la página
544 @translationof Music runs off the page
546 La música que se sale de la página por el margen derecho o que aparece
547 exageradamente comprimida está causada casi siempre por haber
548 introducido una duración incorrecta para una nota, produciendo que la
549 nota final de un compás se extienda más allá de la línea divisoria.
550 Esto no es inválido si la nota final de un compás no termina sobre la
551 línea divisoria introducida automáticamente, pues simplemente se
552 supone que la nota se solapa encima del siguiente compás. Pero si se
553 produce una larga secuencia tales notas solapadas, la música puede
554 aparecer comprimida o salirse de la página porque los saltos de línea
555 automáticos solamente se pueden insertar al final de compases
556 completos, es decir, aquellos en que todas las notas terminan antes de
557 o justo al final del compás.
559 @warning{Una duración incorrecta puede hacer que se inhiban los saltos
560 de línea, lo que llevaría a una sola línea de música muy comprimida o
561 que se salga de la página.}
563 La duración incorrecta se puede encontrar fácilmente si se utilizan
564 comprobaciones de compás, véase @ruser{Comprobación de compás y de
567 Si realmente queremos tener una serie de estos compases con notas
568 solapadas, debemos insertar una línea divisoria invisible donde
569 queramos el salto de línea. Para ver más detalles, consulte
570 @ruser{Barras de compás}.
573 @node Aparece un pentagrama de más
574 @unnumberedsubsec Aparece un pentagrama de más
575 @translationof An extra staff appears
577 Si no se crean los contextos explícitamente con @code{\new}, se
578 crearán discretamente tan pronto como se encuentra una instrucción que
579 no se puede aplicar a un contexto existente. En partituras sencillas,
580 la creación automática de los contextos es útil, y casi todos los
581 ejemplos de los manuales de LilyPond se aprovechan de esta
582 simplificación. Pero ocasionalmente la creación discreta de contextos
583 puede hacer aflorar pentagramas o partituras nuevos e inesperados.
584 Por ejemplo, podría esperarse que el código siguiente hiciera que
585 todas las notas dentro del pentagrama siguiente estuvieran coloreadas
586 de rojo, pero de hecho el resultado son dos pentagramas, permaneciendo
587 el de abajo con las notas en el color negro predeterminado.
589 @lilypond[quote,verbatim,relative=2]
590 \override Staff.NoteHead #'color = #red
594 Esto es así porque no existe ningún contexto @code{Staff} cuando se
595 procesa la instrucción override de sobreescritura, se crea uno
596 implícitamente y la sobreescritura se aplica a éste, pero entonces la
597 instrucción @code{\new Staff} crea un pentagrama nuevo y distinto, en
598 el que se colocan las notas. El código correcto para colorear todas
601 @lilypond[quote,verbatim,relative=2]
603 \override Staff.NoteHead #'color = #red
608 Como segundo ejemplo, si una instrucción @code{\relative} se escribe
609 dentro de una instrucción @code{\repeat}, el resultado son dos
610 pentagramas, el segundo desplazado respecto al primero, porque la
611 instrucción @code{\repeat} genera dos bloques @code{\relative},
612 cada uno de los cuales crea implícitamente bloques @code{Staff} y
615 @lilypond[quote,verbatim]
617 \relative c' { c d e f }
621 La forma correcta es invertir el orden de las instrucciones
622 @code{\repeat} y @code{\relative}, así:
624 @lilypond[quote,verbatim]
626 \repeat unfold 2 { c d e f }
631 @node Error aparente en ../ly/init.ly
632 @unnumberedsubsubsec Error aparente en @code{../ly/init.ly}
633 @translationof Apparent error in ../ly/init.ly
635 Pueden aparecer varios mensajes de error extraños acerca de errores de
636 sintaxis en @code{../ly/init.ly} si el archivo de entrada no está
637 correctamente formado, por ejemplo si no contiene llaves o comillas
638 correctamente emparejados.
640 El error más común es la falta de una llave de cierre, (@code{@}}), al
641 final de un bloque @code{score}. Aquí la solución es obvia: compruebe
642 que el bloque @code{score} está correctamente cerrado. La estructura
643 correcta de un archivo de entrada está descrita en @ref{Cómo funcionan
644 los archivos de entrada de LilyPond}. Usando un editor que resalte
645 automáticamente las llaves correspondientes es de mucha ayuda para
646 evitar estos errores.
648 Una segunda causa frecuente es la falta de un espacio entre la última
649 sílaba de un bloque lyrics (de letra) y la llave de cierre,
650 (@code{@}}). Sin esta separación, se considera que la llave forma
651 parte de la sílaba. Siempre se aconseja asegurarse de que hay
652 espacios antes y después de @emph{todas} las llaves. Para conocer la
653 importancia de este asunto al utilizar letras de canciones, consulte
654 @ruser{Explicación de la letra}.
656 Este mensaje de error también puede aparecer si se omiten las comillas
657 de terminación (@code{"}). En este caso, un mensaje de error
658 adicional debería indicar un número de línea cercano al de aquella
659 donde está el error. Las comillas desbalanceadas estarán por lo
660 general una o dos líneas por encima.
663 @node Mensaje de error Unbound variable %
664 @unnumberedsubsubsec Mensaje de error Unbound variable %
665 @translationof Error message Unbound variable %
667 Este mensaje de error aparece al final de los mensajes de la consola o
668 del archivo de registro junto a un mensaje @qq{GUILE señaló un error
669 ...} cada vez que se llame a una rutina de Scheme que
670 (incorrectamente) contenga un comentario @emph{de LilyPond} en lugar
671 de un comentario @emph{de Scheme}.
673 Los comentarios de LilyPond comienzan con un símbolo de porcentaje,
674 (@code{%}), y no se deben utilizar dentro de las rutinas de Scheme.
675 Los comentarios de Scheme comienzan con punto y coma, (@code{;}).
678 @node Mensaje de error FT_Get_Glyph_Name
679 @unnumberedsubsec Mensaje de error FT_Get_Glyph_Name
680 @translationof Error message FT_Get_Glyph_Name
682 Este mensaje de error aparece en la salida de la consola o en el
683 archivo log de registro si un archivo de entrada contiene un carácter
684 que no es ASCII y no se ha guardado en la codificación de caracteres
685 UTF-8. Para ver más detalles, consulte @ruser{Codificación del