1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of lilypond-program.tely
4 Translation of GIT committish: 29cfaa52797fccf18ae4f25da5e828d10b46b65a
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{MacOS X on the
52 La descripción del uso de esta parte de los sistemas operativos se
53 sale del ámbito de este manuual; le rogamos que consulte otros
54 documentos sobre este tema si no le resulta familiar la línea de
59 * Command line options::
60 * Environment variables::
63 @node Invoking lilypond
64 @subsection Invoking lilypond
66 @cindex invocar a LilyPond
67 @cindex opciones de la línea de órdenes
68 @cindex órdenes, opciones de la línea de
70 El ejecutable @command{lilypond} se puede llamar desde la línea de
71 órdenes de la siguiente manera:
74 lilypond [@var{opción}]@dots{} @var{archivo}@dots{}
77 Cuando se invoca con un nombre de archivo sin extensión, se prueba en
78 primer lugar con la extensión @file{.ly}. Para leer la entrada desde
79 stdin, utilice un guión (@code{-}) en sustitución de @var{archivo}.
81 Cuando se procesa @file{archivo.ly}, la salida resultante son los
82 archivos @file{archivo.ps} y @file{archivo.pdf}. Se pueden
83 especificar varios archivos; cada uno de ellos se procesará de forma
84 independiente@footnote{El estado de GUILE no se restablece después de
85 procesar un archivo @code{.ly}, por lo que debe tener cuidado de no
86 modificar ningún valor predeterminado desde dentro de Scheme.}.
88 Si @file{archivo.ly} contiene más de un bloque @code{\score}, el resto
89 de las partituras se obtendrán como salida en archivos numerados,
90 empezando por @file{archivo-1.pdf}. además, el valor de
91 @code{output-suffix} (sufijo de salida) se insertará entre el nombre
92 base y el número. Un archivo de entrada que contenga
95 #(define output-suffix "violin")
97 #(define output-suffix "cello")
102 producirá como salida @var{base}@file{-violin.pdf} y
103 @var{base}@file{-cello-1.pdf}.
106 @node Command line options
107 @subsection Command line options
109 Están contempladas las siguientes opciones:
113 @item -e,--evaluate=@var{expresión}
114 Evaluar la @var{expresión} de Scheme antes de analizar los archivos
115 @file{.ly}. Se pueden pasar varias opciones @code{-e}, que se
116 evaluarán en secuencia.
118 La expresión se evaluará en el módulo @code{guile-user}, de manera que
119 si quiere usar definiciones dentro de @var{expresión}, debe utilizar
122 lilypond -e '(define-public a 42)'
126 en la línea de órdenes, e incluir
129 #(use-modules (guile-user))
133 al principio del archivo @code{.ly}.
135 @item -f,--format=@var{formato}
136 Qué formatos se tienen que escribir. Como @code{formato} se puede
137 elegir entre @code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}
140 Ejemplo: @code{lilypond -fpng @var{archivo}.ly}
142 @item -d,--define-default=@var{variable}=@var{valor}
143 Establece la opción interna del programa @var{variable} al valor de
144 Scheme @var{valor}. Si no se proporciona ningún @var{valor}, se usa
145 @var{#t}. Para desactivar una opción se puede anteponer @code{no-} a
146 la @var{variable}, p.ej.:
148 @cindex apuntar y pulsar, línea de órdenes
157 -dpoint-and-click='#f'
160 A continuación veremos algunas opciones interesantes.
164 La ejecución de @code{lilypond -dhelp} imprimirá todas las opciones
165 @code{-d} que están disponibles.
168 Esta opción establece el tamaño predeterminado del papel,
170 -dpaper-size=\"letter\"
174 Observe que la cadena se debe incluir dentro de comillas escapadas
179 No confiar en la entrada @code{.ly}.
181 Cuando el proceso de tipografía de LilyPond se encuentra disponible a
182 través de un servidor web, @b{SE DEBEN} pasar las opciones
183 @code{--safe} (seguro) o @code{--jail} (jaula). La opción
184 @code{--safe} evita que el código de Scheme en línea arme un desastre,
191 c4^#(ly:export (ly:gulp-file "/etc/passwd"))
196 La opción @code{-dsafe} funciona evaluando las expresiones en línea de
197 Scheme dentro de un módulo especial seguro. Este módulo seguro deriva
198 del módulo GUILE @file{safe-r5rs}, pero añade ciertas funciones del
199 API de LilyPond. Estas funciones se relacionan en
200 @file{scm/@/safe@/-lily@/.scm}.
202 Además, el modo seguro prohíbe las directivas @code{\include} e
203 inhabilita el uso de barras invertidas en las cadenas de @TeX{}.
205 En el modo seguro, no es posible la importación de variables de
206 LilyPond dentro de Scheme.
208 @code{-dsafe} @emph{no} detecta la sobreutilización de recursos. Aún
209 es posible hacer que el programa se cuelgue indefinidamente, por
210 ejemplo alimentándo el backend con estructuras de datos cíclicas. Por
211 tanto, si se está utilizando LilyPond sobre un servidor web accesible
212 públicamente, el proceso debe limitarse tanto en el uso de CPU como de
215 El modo seguro impide que muchos fragmentos útiles de código de
216 LilyPond se puedan compilar. La opción @code{--jail} es una
217 alternativa más segura, pero su preparación requiere más trabajo.
220 el formato de salida que usar para el back-end o extremo final.
221 Para el @code{formato} se puede elegir entre
224 para una salida en @TeX{} con destino a su proceso por parte de
225 La@TeX{}. Si el archivo @file{file.textmetrics} está presente, se lee
226 para determinar las dimensiones del texto.
228 volcar cadenas de texto en un archivo @file{.texstr}, que se puede
229 procesar con (La)@TeX{}, dando como resultado un archivo
230 @code{.textmetrics} que contiene las dimensiones de las cadenas de
231 texto. @strong{Arvertencia:} esta funcionalidad no está disponible
232 actualmente debido a la profunda reestructuración del código fuente.
236 @cindex PostScript, salida
238 Los archivos PostScript incluyen las tipografías TTF, Type1 y OTF. No
239 se seleccionan subconjuntos de estas tipografías. Cuando se usan
240 conjuntos de caracteres orientales, esto puede dar lugar a archivos
244 para obtener PostScript encapsulado. Esto vuelca cada una de las
245 páginas/sistemas como un archivo @file{EPS} distinto, sin tipografías,
246 y como un solo archivo @file{EPS} encuadernado con todas las
247 páginas/sistemas con las tipografías incluidas.
249 Este modo se usa de forma predeterminada por parte de
250 @command{lilypond-book}.
253 para obtener SVG (gráficos vectoriales escalables). Vuelca cada
254 página como un archivo @file{SVG} distinto, con las tipografías
256 @cindex SVG (gráficos vectoriales escalables)
257 Se necesita un visor de SVG que contemple las tipografías
258 incrustadas, o un visor de SVG que pueda sustituir las tipografías
259 incrustadas por tipografías OTF. Bajo UNIX, puede usar
260 @uref{http://www.inkscape.org,Inkscape} (versión 0.42 o posterior),
261 después de copiar las tipografías OTF del directorio de LilyPond (que
262 normalmente es @file{/usr/share/lilypond/VERSIÓN/fonts/otf/}) al
263 directorio @file{~/.fonts/}.
265 para obtener un volcado de las instrucciones internas de dibujo
266 basadas en Scheme, en bruto.
267 @cindex Scheme, volcado de
270 Ejemplo: @code{lilypond -dbackend=svg @var{archivo}.ly}
272 @cindex salida, establecer el formato de
275 Generar un archivo de salida que contenga solamente los títulos de
276 cabecera y el primer sistema de la primera página.
279 Generar las páginas completas, el ajuste predeterminado.
280 @code{-dno-print-pages} es útil en combinación con @code{-dpreview}.
287 Mostrar un resumen de las formas de utilización.
289 @item -H,--header=@var{CAMPO}
290 Volcar un campo de cabecera al archivo @file{NOMBREBASE.@var{CAMPO}}
292 @item --include, -I=@var{directorio}
293 Añadir el @var{directorio} a la ruta de búsqueda de archivos de
295 @cindex archivos, búsqueda de
296 @cindex búsqueda, ruta de
298 @item -i,--init=@var{archivo}
299 Establecer el archivo de inicio a @var{archivo} (predeterminado:
302 @item -o,--output=@var{ARCHIVO}
303 Establecer el nombre del archivo de salida predeterminado a
304 @var{ARCHIVO}. Se añade el sufijo correspondiente (es decir,
305 @code{.pdf} para PDF, @code{.tex} para TeX, etc.).
311 Generar archivos DVI files. En este caso se debe especificar el
312 backend @TeX{}, es decir: @code{-dbackend=tex}.
315 Generar imágenes de las páginas en formato PNG. Esto implica
316 @code{--ps}. La resolución en PPP de la imagen se puede establecer
323 Generar PDF. Implica @code{--ps}.
327 @item -j,--jail=@var{usuario},@var{grupo},@var{jaula},@var{directorio}
328 Ejecutar @command{lilypond} en una jaula de chroot.
330 La opción @code{--jail} (jaula) proporciona una alternativa más
331 flexible a la opción @code{--safe} cuando el proceso de tipografía de
332 LilyPond está disponible a través de un servidor web o cuando LilyPond
333 ejecuta archivos fuente procedentes del exterior.
335 La opción @code{--jail} funciona cambiando la raíz de
336 @command{lilypond} a @var{jaula} justo antes de comenzar el proceso de
337 compilación en sí. Entonces se cambian el usuario y el grupo a los
338 que se han dado en la opción, y el directorio actual se cambia a
339 @var{directorio}. Esta instalación garantiza que no es posible, al
340 menos en teoría, escapar de la jaula. Observe que para que funcione
341 @code{--jail} se debe ejecutar @command{lilypond} como root, lo que
342 normalmente se puede hacer de una forma segura utilizando
345 La instalación de una jaula es un asunto algo delicado, pues debemos
346 asegurarnos de que LilyPond puede encontrar @emph{dentro de la jaula}
347 todo lo que necesita para poder compilar la fuente. Una configuración
348 típica consta de los siguientes elementos:
351 @item Preparar un sistema de archivos separado
352 Se debe crear un sistema de archivos separado para LilyPond, de forma
353 que se pueda montar con opciones seguras como @code{noexec},
354 @code{nodev} y @code{nosuid}. De esta forma, es imposible ejecutar
355 programas o escribir directamente a un dispositivo desde LilyPond. Si
356 no quiere crear una partición separada, tan sólo tiene que crear un
357 archivo de un tamaño razonable y usarlo para montar un dispositivo
358 loop. El sistema de archivos separado garantiza también que LilyPond
359 nunca pueda escribir en un espacio mayor del que se le permita.
361 @item Preparar un usuario separado
362 Se debe usar un usuario y grupo separados (digamos
363 @code{lily}/@code{lily}) con bajos privilegios para ejecutar LilyPond
364 dentro de la jaula. Debería existir un solo directorio con permisos
365 de escritura para este usuario, y debe pasarse en el valor
368 @item Preparar la jaula
369 LilyPond necesita leer algunos archivos mientras se ejecuta. Todos
370 estos archivos se deben copiar dentro de la jaula, bajo la misma ruta
371 en que aparecen en el sistema de archivos real de root. Todo el
372 contenido de la instalación de LilyPond (por ejemplo
373 @file{/usr/share/lilypond}) se debe copiar.
375 Si surgen problemas, la forma más sencilla de rastrearlos es ejecutar
376 LilyPond usando @command{strace}, lo que le permitirá determinar qué
379 @item Ejecutar LilyPond
380 Dentro de una jaula montada con @code{noexec} es imposible ejecutar
381 ningún programa externo. Por tanto, LilyPond se debe ejecutar con un
382 backend que no necesite tal programa. Como ya mencionamos, también se
383 debe ejecutar con privilegios del superusuario (que por supuesto
384 perderá inmediatamente), posiblemente usando @command{sudo}. Es buena
385 idea limitar el número de segundos de tiempo de CPU que LilyPond puede
386 usar (p.ej., usando @command{ulimit -t}), y, si su sistema operativo
387 lo contempla, el tamaño de la memoria que se puede reservar.
392 Mostrar la información de la versión.
395 Ser prolijo: mostrar las rutas completas de todos los archivos que se
396 leen, y dar información cronométrica.
399 Mostrar la garantía con que viene GNU LilyPond (¡no viene con
400 @strong{NINGUNA GARANTÍA}!).
403 @node Environment variables
404 @subsection Environment variables
408 @cindex LILYPOND_DATADIR
410 @command{lilypond} reconoce las siguientes variables de entorno:
412 @item LILYPOND_DATADIR
413 Especifica un directorio en el que los mensajes de localización y de
414 datos se buscarán de forma predeterminada. El directorio debe
415 contener subdirectorios llamados @file{ly/}, @file{ps/}, @file{tex/},
419 Selecciona el idioma de los mensajes de advertencia.
421 @item LILYPOND_GC_YIELD
422 Con esta variable se puede ajustar la huella y el desempeño de
423 memoria. Es un porcentaje que ajusta el comportamiento de la
424 administración de memoria. Con valores más altos, el programa usa más
425 memoria; con valores más bajos, usa más tiempo de CPU. El valor
426 predeterminado es @code{70}.
432 @section Error messages
434 @cindex error, mensajes de
435 @cindex mensajes de error
437 Pueden aparecer distintos mensajes de error al compilar un archivo:
443 Algo tiene un aspecto sospechoso. Si estamos pidiendo algo fuera de
444 lo común, entenderemos el mensaje y podremos ignorarlo. Sin embargo,
445 las advertencias suelen indicar que algo va mal con el archivo de
450 Algo va claramente mal. El paso actual de procesamiento (análisis,
451 interpretación o formateo visual) se dará por terminado, pero el
452 siguiente paso se saltará.
457 Algo va claramente mal, y LilyPond no puede seguir. Rara vez sucede
458 esto. La causa más frecuente son las tipografías mal instaladas.
460 @item Error de Scheme
461 @cindex traza de Scheme
462 @cindex llamadas, traza de
463 @cindex Scheme, error de
464 @cindex error de Scheme
465 Los errores que ocurren al ejecutar código de Schheme se interceptan
466 por parte del intérprete de Scheme. Si se está ejecutando con las
467 opciones @code{-V} o @code{--verbose} (prolijo) entonces se imprime
468 una traza de llamadas de la función ofensiva.
470 @item Error de programación
471 @cindex error de programación
472 @cindex programación, error de
473 Ha habido algún tipo de inconsistencia interna. Estos mensajes de
474 error están orientados a ayudar a los programadores y a los
475 depuradores. Normalmente se pueden ignorar. En ocasiones aparecen en
476 cantidades tan grandes que pueden entorpecer la visión de otros
479 @item Abortado (volcado de core)
480 Esto señala un error de programación serio que ha causado la
481 interrupción abrupta del programa. Estos errores se consideran
482 críticos. Si se topa con uno, envíe un informe de fallo.
485 @cindex error, formato de los mensajes de
487 Se los errores y advertencias se pueden ligar a un punto del archivo
488 de entrada, los mensajes tienen la forma siguiente:
491 @var{archivo}:@var{línea}:@var{columna}: @var{mensaje}
492 @var{línea de entrada problemática}
495 Se inserta un salto de línea en la línea problemática para indicar la
496 columna en que se encontró el error. Por ejemplo,
499 prueba.ly:2:19: error: no es una duración: 5
504 Estas posiciones son la mejor suposición de LilyPond sobre dónde se ha
505 producido el mensaje de error, pero (por su propia naturaleza) las
506 advertencias y errores se producen cuando ocurre algo inesperado. Si
507 no ve un error en la línea que se indica del archivo de entrada, trate
508 de comprobar una o dos líneas por encima de la posición indicada.
511 @node Updating files with convert-ly
512 @section Updating with @command{convert-ly}
514 @cindex actualización de un archivo de LilyPond
516 @cindex versión de los archivos
519 La sintaxis del lenguaje de entrada de LilyPond se modifica de forma
520 habitual para simplificarla o mejorarla de distintas maneras. Como
521 efecto secundario, el intérprete de LilyPond a menudo ya no es
522 compatible con los archivos de entrada antiguos. Para poner remedio a
523 esto se puede utilizar el programa @command{convert-ly} para manejar
524 casi todos los cambios de sintaxis entre versiones de LilyPond.
526 Utiliza los enunciados @code{\version} de los archivos de entrada para
527 detectar el número de versión antiguo. En casi todos los casos, para
528 actualizar el archivo de entrada basta con ejecutar
531 convert-ly -e miarchivo.ly
535 Los usuarios de MacOS@tie{}X pueden ejecutar esta instrucción bajo el
536 menú @code{Compilar > Actualizar sintaxis}.
538 Si no hay cambios en miarchivo.ly y se crea el archivo llamado
539 miarchivo.ly.NEW, entonces miarchivo.ly ya está actualizado.
541 @subsection Command line options
543 @command{convert-ly} convierte siempre al últimmo cambio de sintaxis
544 que puede manejar. Eesto supone que el número de @code{\version} que
545 aparece en el archivo convertido suele ser más bajo que la versión del
546 propio programa @command{convert-ly}.
548 Para actualizar fragmentos de LilyPond en archivos de texinfo, use
551 convert-ly --from=... --to=... --no-version *.itely
554 Para ver los cambios en la sintaxis de LilyPond entre dos versiones,
558 convert-ly --from=... --to=... -s
561 Para actualizar muchos archivos de una vez, combine @code{convert-ly}
562 con las instrucciones estándar de UNIX. Este ejemplo actualiza todos
563 los archivos @code{.ly} del directorio actual:
566 for f in *.ly; do convert-ly -e $f; done;
569 En general, el programa se invoca de la manera siguiente:
572 convert-ly [@var{opción}]@dots{} @var{archivo}@dots{}
576 Se pueden dar las siguientes opciones:
580 Hace una edición en línea del archivo de entrada. Sobreescribe a
583 @item -f,--from=@var{versión_de_origen}
584 Establece la versión desde la que convertir. Si no aparece esta
585 opción, @command{convert-ly} tratará de adivinarla, basándose en el
586 enunciado @code{\version} del archivo.
588 @item -n,--no-version
589 Normalmente @command{convert-ly} añade un indicador @code{\version} a
590 la salida. La especificación de esta opción lo suprime.
592 @item -s, --show-rules
593 Mostrar todas las conversiones conocidas y salir.
595 @item --to=@var{versión_final}
596 Fijar la versión de destino de la conversión. De forma predeterminada
597 se convierte a la última versión disponible.
600 Imprimir la ayuda de la utilización.
605 * Problems with convert-ly::
609 @node Problems with convert-ly
610 @subsection Problems with @code{convert-ly}
612 No se manejan todos los cambios en el lenguaje. S´olo se puede
613 especificar una opción de salida. La actualización automática de
614 Scheme y los interfaces Scheme de LilyPond es bastante improbable;
615 prepárese para trucar el código de Scheme a mano.
618 Hay algunas cosas que convert-ly no puede manejar. He aquí una lista
619 de aquellas limitaciones que han dado lugar a protestas de la
622 Se ha escogido esta estructura de informe de fallo porque convert-ly
623 tiene una estructura que no permite implementar de forma progresiva
624 todos los cambios necesarios. Así pues esto es sólo una lista de
625 deseos, y se incluye aquí como referencia.
628 No siempre convierte el bajo cifrado correctamente, específicamente cosas como {<
629 >}. El comentario de Mats sobre cómo solventar el problema:
630 Para poder ejecutar convert-ly
631 sobre él, primero sustituí todas las apariciones de '{<' a algo mudo como '{#'
632 y de forma similar sustituí '>}' con '&}'. Después de la conversión, pude
633 volver a cambiarlos de '{ #' a '{ <' y de '& }' a '> }'.
634 No convierte todos los marcados de texto correctamente. En sintaxis antigua,
635 se podían agrupar varios marcados entre paréntesis, p.ej.
636 -#'((bold italic) "cadena")
637 Esto se convierte incorrectamente en
638 -\markup{{\bold italic} "cadena"}
640 -\markup{\bold \italic "cadena"}
642 No maneja \partcombine
643 No hace \addlyrics => \lyricsto, esto rompe algunas partituras con varias estrofas.
645 \magnify no se cambia por \fontsize.
646 - \magnify #m => \fontsize #f, donde f = 6ln(m)/ln(2)
647 remove-tag no se cambia.
648 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
649 first-page-number no se cambia.
650 - first-page-number no => print-first-page-number = ##f
651 Los saltos de línea en las cadenas de cabecera no se convierten.
652 - \\\\ como salto de línea en las cadenas de \header => \markup \center-align <
653 "Primera línea" "Segunda línea" >
654 Los terminadores de crescendo y decrescendo no se convierten.
658 \turnOff (usado en \set Staff.VoltaBracket = \turnOff) no se convierte
661 \markup{ \center-align <{ ... }> } se tendría que convertir en:
662 \markup{ \center-align {\line { ... }} }
663 pero ahora, falta el \line.
665 Los caracteres especiales de LaTeX como $~$ en el texto no se convierten a UTF8.
667 \score{} ahora debe empezar con una expresión musical. Cualquier otra cosa
668 (en particular, \header{}) debe ir después de la música.
673 @section Reporting bugs
675 @cindex bugs (fallos)
676 @cindex fallos (bugs)
677 @cindex informes de fallo
679 Si tiene una entrada que produce una interrupción abrupta o una salida
680 errónea, entonces eso es un bug (fallo). Hay una lista de los fallos
681 actuales en nuestro rastreador de fallos de Google Code:
683 @uref{http://code.google.com/p/lilypond/issues/list}
685 Si descubre un error que no está en la lista, le rogramos que envíe un
686 informe del fallo siguiendo las instrucciones que aparecen en
688 @uref{http://lilypond.org/web/devel/participating/bugs}
690 Le rogamos, asimismo, que para los informes prepare y envíe ejemplos
691 mínimos de los fallos. No tenemos los recursos para investigar
692 informes que no sean lo más pequeños posible.