1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
4 Translation of GIT committish: 45945bd973aa9161b10e3f517902afb7ef4b4a56
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
13 @node Running LilyPond
14 @chapter Running LilyPond
16 Este capítulo detalla los aspectos técnicos de la ejecución de
21 * Command-line usage::
23 * Updating files with convert-ly::
31 Casi todos los usuarios ejecutan LilyPond por medio de un interfaz
32 gráfico; consulte @rlearning{First steps} si no lo ha leído aún.
35 @node Command-line usage
36 @section Command-line usage
38 Esta sección contiene información adicional sobre el uso de LilyPond
39 en la línea de órdenes. Esta forma puede ser preferible para pasarle
40 al programa algunas opciones adicionales. Además, existen algunos
41 programas complementarios @q{de apoyo} (como @code{midi2ly}) que sólo
42 están disponibles en la línea de órdenes.
44 Al hablar de la @q{línea de órdenes}, nos referimos a la consola del
45 sistema operativo. Los usuarios de Windows posiblemente estén más
46 familiarizados con los términos @q{ventana de MS-DOS} o @q{línea de
47 comandos}; Los usuarios de MacOS@tie{}X puede que estén más
48 familiarizados con los términos @q{terminal} o @q{consola}. Éstos
49 deberían consultar también el apartado @ref{Setup for MacOS X}.
51 La descripción del uso de esta parte de los sistemas operativos se
52 sale del ámbito de este manual; le rogamos que consulte otros
53 documentos sobre este tema si no le resulta familiar la línea de
58 * Command line options for lilypond::
59 * Environment variables::
62 @node Invoking lilypond
63 @subsection Invoking @command{lilypond}
65 @cindex invocar @command{lilypond}
66 @cindex opciones de la línea de órdenes para @command{lilypond}
67 @cindex órdenes, opciones de la línea de
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 Command line options for lilypond
106 @subsection Command line options for @command{lilypond}
108 Están contempladas las siguientes opciones:
112 @item -e,--evaluate=@var{expresión}
113 Evaluar la @var{expresión} de Scheme antes de analizar los archivos
114 @file{.ly}. Se pueden pasar varias opciones @code{-e}, que se
115 evaluarán en secuencia.
117 La expresión se evaluará en el módulo @code{guile-user}, de manera que
118 si quiere usar definiciones dentro de @var{expresión}, debe utilizar
121 lilypond -e '(define-public a 42)'
125 en la línea de órdenes, e incluir
128 #(use-modules (guile-user))
132 al principio del archivo @code{.ly}.
134 @item -f,--format=@var{formato}
135 Formato de la salida. Como @code{formato} se puede elegir entre
136 @code{svg}, @code{ps}, @code{pdf} y @code{png}.
138 Ejemplo: @code{lilypond -fpng @var{archivo}.ly}
140 @item -d,--define-default=@var{variable}=@var{valor}
141 Establece la opción interna del programa @var{variable} al valor de
142 Scheme @var{valor}. Si no se proporciona ningún @var{valor}, se usa
143 @var{#t}. Para desactivar una opción se puede anteponer @code{no-} a
144 la @var{variable}, p.ej.:
146 @cindex apuntar y pulsar, línea de órdenes
155 -dpoint-and-click='#f'
158 A continuación veremos algunas opciones interesantes.
162 La ejecución de @code{lilypond -dhelp} imprimirá todas las opciones
163 @code{-d} que están disponibles.
166 Esta opción establece el tamaño predeterminado del papel,
168 -dpaper-size=\"letter\"
172 Observe que la cadena se debe incluir dentro de comillas escapadas
175 @c Match " in previous line to help context-sensitive editors
178 No confiar en la entrada @code{.ly}.
180 Cuando el proceso de tipografía de LilyPond se encuentra disponible a
181 través de un servidor web, @b{SE DEBEN} pasar las opciones
182 @code{--safe} (seguro) o @code{--jail} (jaula). La opción
183 @code{--safe} evita que el código de Scheme en línea arme un desastre,
190 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
195 La opción @code{-dsafe} funciona evaluando las expresiones en línea de
196 Scheme dentro de un módulo especial seguro. Este módulo seguro deriva
197 del módulo GUILE @file{safe-r5rs}, pero añade ciertas funciones del
198 API de LilyPond. Estas funciones se relacionan en
199 @file{scm/@/safe@/-lily@/.scm}.
201 Además, el modo seguro prohíbe las directivas @code{\include} e
202 inhabilita el uso de barras invertidas en las cadenas de @TeX{}.
204 En el modo seguro, no es posible la importación de variables de
205 LilyPond dentro de Scheme.
207 @code{-dsafe} @emph{no} detecta la sobreutilización de recursos. Aún
208 es posible hacer que el programa se cuelgue indefinidamente, por
209 ejemplo alimentando el backend con estructuras de datos cíclicas. Por
210 tanto, si se está utilizando LilyPond sobre un servidor web accesible
211 públicamente, el proceso debe limitarse tanto en el uso de CPU como de
214 El modo seguro impide que muchos fragmentos útiles de código de
215 LilyPond se puedan compilar. La opción @code{--jail} es una
216 alternativa más segura, pero su preparación requiere más trabajo.
218 @cindex salida, establecer el formato de
220 el formato de salida que usar para el back-end o extremo final.
221 Para el @code{formato} se puede elegir entre
224 @cindex PostScript, salida
227 Los archivos PostScript incluyen las tipografías TTF, Type1 y OTF. No
228 se seleccionan subconjuntos de estas tipografías. Cuando se usan
229 conjuntos de caracteres orientales, esto puede dar lugar a archivos
233 para obtener PostScript encapsulado. Esto vuelca cada una de las
234 páginas/sistemas como un archivo @file{EPS} distinto, sin tipografías,
235 y como un solo archivo @file{EPS} encuadernado con todas las
236 páginas/sistemas con las tipografías incluidas.
238 Este modo se usa de forma predeterminada por parte de
239 @command{lilypond-book}.
242 @cindex SVG (Scalable Vector Graphics)
243 para obtener SVG (gráficos vectoriales escalables).
245 Crea un único archivo SVG que contiene toda la salida de música, con
246 las tipografías incrustadas. Se necesita un visor de SVG que
247 contemple las tipografías incrustadas, o un visor de SVG que pueda
248 sustituir las tipografías incrustadas por tipografías OTF. Bajo UNIX,
249 puede usar @uref{http://www.inkscape.org,Inkscape} (versión 0.42 o
250 posterior), después de copiar las tipografías OTF del directorio de
251 LilyPond (que normalmente es
252 @file{/usr/share/lilypond/VERSIÓN/fonts/otf/}) al directorio
256 @cindex Scheme, volcado de
257 para obtener un volcado de las instrucciones internas de dibujo
258 basadas en Scheme, en bruto.
260 no producir una salida impresa; tiene el mismo efecto que @code{-dno-print-pages}.
263 Ejemplo: @code{lilypond -dbackend=svg @var{archivo}.ly}
266 Generar un archivo de salida que contenga solamente los títulos de
267 cabecera y el primer sistema de la primera página.
270 Generar las páginas completas, el ajuste predeterminado.
271 @code{-dno-print-pages} es útil en combinación con @code{-dpreview}.
278 Mostrar un resumen de las formas de utilización.
280 @item -H,--header=@var{CAMPO}
281 Volcar un campo de cabecera al archivo @file{NOMBREBASE.@var{CAMPO}}
283 @item --include, -I=@var{directorio}
284 Añadir el @var{directorio} a la ruta de búsqueda de archivos de
286 @cindex archivos, búsqueda de
287 @cindex búsqueda, ruta de
289 @item -i,--init=@var{archivo}
290 Establecer el archivo de inicio a @var{archivo} (predeterminado:
293 @item -o,--output=@var{ARCHIVO}
294 Establecer el nombre del archivo de salida predeterminado a
295 @var{ARCHIVO}. Se añade el sufijo correspondiente (por ejemplo,
296 @code{.pdf} para PDF).
302 Generar imágenes de las páginas en formato PNG. Esto implica
303 @code{--ps}. La resolución en PPP de la imagen se puede establecer
310 Generar PDF. Implica @code{--ps}.
312 @item -j,--jail=@var{usuario},@var{grupo},@var{jaula},@var{directorio}
313 Ejecutar @command{lilypond} en una jaula de chroot.
315 La opción @code{--jail} (jaula) proporciona una alternativa más
316 flexible a la opción @code{--safe} cuando el proceso de tipografía de
317 LilyPond está disponible a través de un servidor web o cuando LilyPond
318 ejecuta archivos fuente procedentes del exterior.
320 La opción @code{--jail} funciona cambiando la raíz de
321 @command{lilypond} a @var{jaula} justo antes de comenzar el proceso de
322 compilación en sí. Entonces se cambian el usuario y el grupo a los
323 que se han dado en la opción, y el directorio actual se cambia a
324 @var{directorio}. Esta instalación garantiza que no es posible, al
325 menos en teoría, escapar de la jaula. Observe que para que funcione
326 @code{--jail} se debe ejecutar @command{lilypond} como root, lo que
327 normalmente se puede hacer de una forma segura utilizando
330 La instalación de una jaula es un asunto algo delicado, pues debemos
331 asegurarnos de que LilyPond puede encontrar @emph{dentro de la jaula}
332 todo lo que necesita para poder compilar la fuente. Una configuración
333 típica consta de los siguientes elementos:
336 @item Preparar un sistema de archivos separado
337 Se debe crear un sistema de archivos separado para LilyPond, de forma
338 que se pueda montar con opciones seguras como @code{noexec},
339 @code{nodev} y @code{nosuid}. De esta forma, es imposible ejecutar
340 programas o escribir directamente a un dispositivo desde LilyPond. Si
341 no quiere crear una partición separada, tan sólo tiene que crear un
342 archivo de un tamaño razonable y usarlo para montar un dispositivo
343 loop. El sistema de archivos separado garantiza también que LilyPond
344 nunca pueda escribir en un espacio mayor del que se le permita.
346 @item Preparar un usuario separado
347 Se debe usar un usuario y grupo separados (digamos
348 @code{lily}/@code{lily}) con bajos privilegios para ejecutar LilyPond
349 dentro de la jaula. Debería existir un solo directorio con permisos
350 de escritura para este usuario, y debe pasarse en el valor
353 @item Preparar la jaula
354 LilyPond necesita leer algunos archivos mientras se ejecuta. Todos
355 estos archivos se deben copiar dentro de la jaula, bajo la misma ruta
356 en que aparecen en el sistema de archivos real de root. Todo el
357 contenido de la instalación de LilyPond (por ejemplo
358 @file{/usr/share/lilypond}) se debe copiar.
360 Si surgen problemas, la forma más sencilla de rastrearlos es ejecutar
361 LilyPond usando @command{strace}, lo que le permitirá determinar qué
364 @item Ejecutar LilyPond
365 Dentro de una jaula montada con @code{noexec} es imposible ejecutar
366 ningún programa externo. Por tanto, LilyPond se debe ejecutar con un
367 backend que no necesite tal programa. Como ya mencionamos, también se
368 debe ejecutar con privilegios del superusuario (que por supuesto
369 perderá inmediatamente), posiblemente usando @command{sudo}. Es buena
370 idea limitar el número de segundos de tiempo de CPU que LilyPond puede
371 usar (p.ej., usando @command{ulimit -t}), y, si su sistema operativo
372 lo contempla, el tamaño de la memoria que se puede reservar.
377 Mostrar la información de la versión.
380 Ser prolijo: mostrar las rutas completas de todos los archivos que se
381 leen, y dar información cronométrica.
384 Mostrar la garantía con que viene GNU LilyPond (¡no viene con
385 @strong{NINGUNA GARANTÍA}!).
388 @node Environment variables
389 @subsection Environment variables
393 @cindex LILYPOND_DATADIR
395 @command{lilypond} reconoce las siguientes variables de entorno:
397 @item LILYPOND_DATADIR
398 Especifica un directorio en el que los mensajes de localización y de
399 datos se buscarán de forma predeterminada. El directorio debe
400 contener subdirectorios llamados @file{ly/}, @file{ps/}, @file{tex/},
404 Selecciona el idioma de los mensajes de advertencia.
406 @item LILYPOND_GC_YIELD
407 Con esta variable se puede ajustar la huella y el desempeño de
408 memoria. Es un porcentaje que ajusta el comportamiento de la
409 administración de memoria. Con valores más altos, el programa usa más
410 memoria; con valores más bajos, usa más tiempo de CPU. El valor
411 predeterminado es @code{70}.
417 @section Error messages
419 @cindex error, mensajes de
420 @cindex mensajes de error
422 Pueden aparecer distintos mensajes de error al compilar un archivo:
428 Algo tiene un aspecto sospechoso. Si estamos pidiendo algo fuera de
429 lo común, entenderemos el mensaje y podremos ignorarlo. Sin embargo,
430 las advertencias suelen indicar que algo va mal con el archivo de
435 Algo va claramente mal. El paso actual de procesamiento (análisis,
436 interpretación o formateo visual) se dará por terminado, pero el
437 siguiente paso se saltará.
442 Algo va claramente mal, y LilyPond no puede seguir. Rara vez sucede
443 esto. La causa más frecuente son las tipografías mal instaladas.
445 @item Error de Scheme
446 @cindex traza de Scheme
447 @cindex llamadas, traza de
448 @cindex Scheme, error de
449 @cindex error de Scheme
450 Los errores que ocurren al ejecutar código de Scheme se interceptan
451 por parte del intérprete de Scheme. Si se está ejecutando con las
452 opciones @code{-V} o @code{--verbose} (prolijo) entonces se imprime
453 una traza de llamadas de la función ofensiva.
455 @item Error de programación
456 @cindex error de programación
457 @cindex programación, error de
458 Ha habido algún tipo de inconsistencia interna. Estos mensajes de
459 error están orientados a ayudar a los programadores y a los
460 depuradores. Normalmente se pueden ignorar. En ocasiones aparecen en
461 cantidades tan grandes que pueden entorpecer la visión de otros
464 @item Abortado (volcado de core)
465 Esto señala un error de programación serio que ha causado la
466 interrupción abrupta del programa. Estos errores se consideran
467 críticos. Si se topa con uno, envíe un informe de fallo.
470 @cindex error, formato de los mensajes de
472 Se los errores y advertencias se pueden ligar a un punto del archivo
473 de entrada, los mensajes tienen la forma siguiente:
476 @var{archivo}:@var{línea}:@var{columna}: @var{mensaje}
477 @var{línea de entrada problemática}
480 Se inserta un salto de línea en la línea problemática para indicar la
481 columna en que se encontró el error. Por ejemplo,
484 prueba.ly:2:19: error: no es una duración: 5
489 Estas posiciones son la mejor suposición de LilyPond sobre dónde se ha
490 producido el mensaje de error, pero (por su propia naturaleza) las
491 advertencias y errores se producen cuando ocurre algo inesperado. Si
492 no ve un error en la línea que se indica del archivo de entrada, trate
493 de comprobar una o dos líneas por encima de la posición indicada.
496 @node Updating files with convert-ly
497 @section Updating files with @command{convert-ly}
499 @cindex actualización de un archivo de LilyPond
502 La sintaxis del lenguaje de entrada de LilyPond se modifica de forma
503 habitual para simplificarla o mejorarla de distintas maneras. Como
504 efecto secundario, el intérprete de LilyPond a menudo ya no es
505 compatible con los archivos de entrada antiguos. Para poner remedio a
506 esto se puede utilizar el programa @command{convert-ly} para manejar
507 casi todos los cambios de sintaxis entre versiones de LilyPond.
510 * Invoking convert-ly::
511 * Command line options for convert-ly::
512 * Problems with convert-ly::
515 @node Invoking convert-ly
516 @subsection Invoking @command{convert-ly}
518 @command{convert-ly} utiliza los enunciados @code{\version} de los
519 archivos de entrada para detectar el número de versión antiguo. En
520 casi todos los casos, para actualizar el archivo de entrada basta con
524 convert-ly -e miarchivo.ly
528 dentro del directorio que contiene el archivo. Con esto se actualiza
529 @code{miarchivo.ly} @emph{in situ} y se preserva el archivo original
530 @code{miarchivo.ly~}.
532 Para convertir de una vez todos los archivos de entrada que hay en un
540 De forma alternativa, si queremos especificar un nombre distinto para
541 el archivo actualizado, preservando el archivo original con el mismo
545 convert-ly miarchivo.ly > minuevoarchivo.ly
548 @command{convert-ly} siempre convierte al último cambio de sintaxis
549 que es capaz de manejar. Esto supone que el número de @code{\version}
550 que aparece en el archivo convertidoo suele ser más bajo que la
551 versión del propio programa @command{convert-ly}.
553 El programa imprimirá una relación de los números de versión para los
554 que se han hecho conversiones. Si no se imprime ningún número de
555 versión, el archivo ya está actualizado.
558 Los usuarios de MacOS@tie{}X pueden ejecutar esta instrucción bajo el
559 menú @code{Compilar > Actualizar sintaxis}.
561 Los usuarios de Windows deben introducir esta instrucción en una
562 ventana del terminal del sistema, que se encuentra por lo general bajo
563 @code{Inicio > Accesorios > Símbolo del sistema}.
566 @node Command line options for convert-ly
567 @subsection Command line options for @command{convert-ly}
570 En general, el programa se invoca de la manera siguiente:
573 convert-ly [@var{opción}]@dots{} @var{archivo}@dots{}
577 Se pueden dar las siguientes opciones:
581 Aplicar las conversiones directamente al archivo de entrada,
582 modificándolo in situ.
584 @item -f,--from=@var{versión_de_origen}
585 Establece la versión desde la que convertir. Si no aparece esta
586 opción, @command{convert-ly} tratará de adivinarla, basándose en el
587 enunciado @code{\version} del archivo. Ejemplo: @code{--from=2.10.25}
589 @item -n,--no-version
590 Normalmente @command{convert-ly} añade un indicador @code{\version} a
591 la salida. La especificación de esta opción lo suprime.
593 @item -s, --show-rules
594 Mostrar todas las conversiones conocidas y salir.
596 @item --to=@var{versión_final}
597 Fijar la versión de destino de la conversión. De forma predeterminada
598 se convierte a la última versión disponible.
601 Imprimir la ayuda de la utilización.
604 Para actualizar fragmentos de LilyPond en archivos de texinfo, use
607 convert-ly --from=... --to=... --no-version *.itely
610 Para ver los cambios en la sintaxis de LilyPond entre dos versiones
614 convert-ly --from=... --to=... -s
618 @node Problems with convert-ly
619 @subsection Problems with @code{convert-ly}
621 Al ejecutar convert-ly en una ventana del Símbolo del Sistema bajo
622 Windows sobre un archivo que tiene espacios en el nombre o en la ruta,
623 es necesario encerrar todo el nombre del archivo de entrada con tres
624 (!) pares de comillas:
627 convert-ly """D:/Mis partituras/Oda.ly""" > "D:/Mis partituras/nueva Oda.ly"
630 Si la orden simple @command{convert-ly -e *.ly} no funciona porque la
631 instrucción expandida se hace muy larga, en vez de ello la orden
632 @command{convert-ly} se puede poner dentro de un bucle. Este ejemplo
633 para UNIX actualiza todos los documentos @code{.ly} del directorio
637 for f in *.ly; do convert-ly -e $f; done;
640 En la ventana del terminal de órdenes de Windows, la instrucción
644 for %x in (*.ly) do convert-ly -e """%x"""
647 No se manejan todos los cambios en el lenguaje. Sólo se puede
648 especificar una opción de salida. La actualización automática de
649 Scheme y los interfaces Scheme de LilyPond es bastante improbable;
650 prepárese para trucar el código de Scheme a mano.
653 Hay algunas cosas que convert-ly no puede manejar. He aquí una lista
654 de aquellas limitaciones que han dado lugar a protestas de la
657 Se ha escogido esta estructura de informe de fallo porque convert-ly
658 tiene una estructura que no permite implementar de forma progresiva
659 todos los cambios necesarios. Así pues esto es sólo una lista de
660 deseos, y se incluye aquí como referencia.
663 No siempre convierte el bajo cifrado correctamente, específicamente cosas como {<
664 >}. El comentario de Mats sobre cómo solventar el problema:
665 Para poder ejecutar convert-ly
666 sobre él, primero sustituí todas las apariciones de '{<' a algo mudo como '{#'
667 y de forma similar sustituí '>}' con '&}'. Después de la conversión, pude
668 volver a cambiarlos de '{ #' a '{ <' y de '& }' a '> }'.
669 No convierte todos los marcados de texto correctamente. En sintaxis antigua,
670 se podían agrupar varios marcados entre paréntesis, p.ej.
671 -#'((bold italic) "cadena")
672 Esto se convierte incorrectamente en
673 -\markup{{\bold italic} "cadena"}
675 -\markup{\bold \italic "cadena"}
677 No maneja \partcombine
678 No hace \addlyrics => \lyricsto, esto rompe algunas partituras con varias estrofas.
680 \magnify no se cambia por \fontsize.
681 - \magnify #m => \fontsize #f, donde f = 6ln(m)/ln(2)
682 remove-tag no se cambia.
683 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
684 first-page-number no se cambia.
685 - first-page-number no => print-first-page-number = ##f
686 Los saltos de línea en las cadenas de cabecera no se convierten.
687 - \\\\ como salto de línea en las cadenas de \header => \markup \center-align <
688 "Primera línea" "Segunda línea" >
689 Los terminadores de crescendo y decrescendo no se convierten.
693 \turnOff (usado en \set Staff.VoltaBracket = \turnOff) no se convierte
696 \markup{ \center-align <{ ... }> } se tendría que convertir en:
697 \markup{ \center-align {\line { ... }} }
698 pero ahora, falta el \line.
700 Los caracteres especiales de LaTeX como $~$ en el texto no se convierten a UTF8.
702 \score{} ahora debe empezar con una expresión musical. Cualquier otra cosa
703 (en particular, \header{}) debe ir después de la música.
708 @section Reporting bugs
710 @cindex bugs (fallos)
711 @cindex fallos (bugs)
712 @cindex informes de fallo
714 Si tiene una entrada que produce una interrupción abrupta o una salida
715 errónea, entonces eso es un bug (fallo). Hay una lista de los fallos
716 actuales en nuestro rastreador de fallos de Google Code:
718 @uref{http://code.google.com/p/lilypond/issues/list}
720 Si descubre un error que no está en la lista, le rogamos que envíe un
721 informe del fallo siguiendo las instrucciones que aparecen en
723 @uref{http://lilypond.org/web/devel/participating/bugs}
725 Le rogamos, asimismo, que para los informes prepare y envíe ejemplos
726 mínimos de los fallos. No tenemos los recursos para investigar
727 informes que no sean lo más pequeños posible.