1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of lilypond-program.tely
4 Translation of GIT committish: 428e134611498913292fb4903602fec97a8a9b65
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 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 safe @emph{no} detecta la sobreutilización de recursos. Aún es
209 posible hacer que el programa se cuelgue indefinidamente, por ejemplo
210 alimentándo el backend con estructuras de datos cíclicas. Por tanto,
211 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 lilypond-book.
252 para obtener SVG (gráficos vectoriales escalables). Vuelca cada
253 página como un archivo @file{SVG} distinto, con las tipografías
255 @cindex SVG (gráficos vectoriales escalables)
256 Se necesita un visor de SVG que contemple las tipografías
257 incrustadas, o un visor de SVG que pueda sustituir las tipografías
258 incrustadas por tipografías OTF. Bajo UNIX, puede usar
259 @uref{http://www.inkscape.org,Inkscape} (versión 0.42 o posterior),
260 después de copiar las tipografías OTF que están en el directorio
261 @file{RUTA/HACIA/share/lilypond/VERSIÓN/fonts/otf/} al directorio
264 para obtener un volcado de las instrucciones internas de dibujo
265 basadas en Scheme, en bruto.
266 @cindex Scheme, volcado de
269 Ejemplo: @code{lilypond -dbackend=svg archivo.ly}
271 @cindex salida, establecer el formato de
274 Generar un archivo de salida que contenga solamente los títulos de
275 cabecera y el primer sistema de la primera página.
278 Generar las páginas completas, el ajuste predeterminado.
279 @code{-dno-print-pages} es útil en combinación con @code{-dpreview}.
286 Mostrar un resumen de las formas de utilización.
288 @item -H,--header=CAMPO
289 Volcar un campo de cabecera al archivo NOMBREBASE.CAMPO
291 @item --include, -I=@var{directorio}
292 Añadir el @var{directorio} a la ruta de búsqueda de archivos de
294 @cindex archivos, búsqueda de
295 @cindex búsqueda, ruta de
297 @item -i,--init=@var{archivo}
298 Establecer el archivo de inicio a @var{archivo} (predeterminado:
301 @item -o,--output=@var{ARCHIVO}
302 Establecer el nombre del archivo de salida predeterminado a
303 @var{ARCHIVO}. Se añade el sufijo correspondiente (es decir,
304 @code{.pdf} para PDF, @code{.tex} para TeX, etc.).
310 Generar archivos DVI files. En este caso se debe especificar el
311 backend @TeX{}, es decir: @code{-dbackend=tex}.
314 Generar imágenes de las páginas en formato PNG. Esto implica
315 @code{--ps}. La resolución en PPP de la imagen se puede establecer
322 Generar PDF. Implica @code{--ps}.
326 @item -j,--jail=@var{usuario},@var{grupo},@var{jaula},@var{directorio}
327 Ejecutar @command{lilypond} en una jaula de chroot.
329 La opción @code{--jail} (jaula) proporciona una alternativa más
330 flexible a la opción @code{--safe} cuando el proceso de tipografía de
331 LilyPond está disponible a través de un servidor web o cuando LilyPond
332 ejecuta archivos fuente procedentes del exterior.
334 La opción @code{--jail} funciona cambiando la raíz de
335 @command{lilypond} a @var{jaula} justo antes de comenzar el proceso de
336 compilación en sí. Entonces se cambian el usuario y el grupo a los
337 que se han dado en la opción, y el directorio actual se cambia a
338 @var{directorio}. Esta instalación garantiza que no es posible, al
339 menos en teoría, escapar de la jaula. Observe que para que funcione
340 @code{--jail} se debe ejecutar @command{lilypond} como root, lo que
341 normalmente se puede hacer de una forma segura utilizando
344 La instalación de una jaula es un asunto algo delicado, pues debemos
345 asegurarnos de que LilyPond puede encontrar @emph{dentro de la jaula}
346 todo lo que necesita para poder compilar la fuente. Una configuración
347 típica consta de los siguientes elementos:
350 @item Preparar un sistema de archivos separado
351 Se debe crear un sistema de archivos separado para LilyPond, de forma
352 que se pueda montar con opciones seguras como @code{noexec},
353 @code{nodev} y @code{nosuid}. De esta forma, es imposible ejecutar
354 programas o escribir directamente a un dispositivo desde LilyPond. Si
355 no quiere crear una partición separada, tan sólo tiene que crear un
356 archivo de un tamaño razonable y usarlo para montar un dispositivo
357 loop. El sistema de archivos separado garantiza también que LilyPond
358 nunca pueda escribir en un espacio mayor del que se le permita.
360 @item Preparar un usuario separado
361 Se debe usar un usuario y grupo separados (digamos
362 @code{lily}/@code{lily}) con bajos privilegios para ejecutar LilyPond
363 dentro de la jaula. Debería existir un solo directorio con permisos
364 de escritura para este usuario, y debe pasarse en el valor
367 @item Preparar la jaula
368 LilyPond necesita leer algunos archivos mientras se ejecuta. Todos
369 estos archivos se deben copiar dentro de la jaula, bajo la misma ruta
370 en que aparecen en el sistema de archivos real de root. Todo el
371 contenido de la instalación de LilyPond (por ejemplo
372 @file{/usr/share/lilypond}) se debe copiar.
374 Si surgen problemas, la forma más sencilla de rastrearlos es ejecutar
375 LilyPond usando @command{strace}, lo que le permitirá determinar qué
378 @item Ejecutar LilyPond
379 Dentro de una jaula montada con @code{noexec} es imposible ejecutar
380 ningún programa externo. Por tanto, LilyPond se debe ejecutar con un
381 backend que no necesite tal programa. Como ya mencionamos, también se
382 debe ejecutar con privilegios del superusuario (que por supuesto
383 perderá inmediatamente), posiblemente usando @command{sudo}. Es buena
384 idea limitar el número de segundos de tiempo de CPU que LilyPond puede
385 usar (p.ej., usando @command{ulimit -t}), y, si su sistema operativo
386 lo contempla, el tamaño de la memoria que se puede reservar.
391 Mostrar la información de la versión.
394 Ser prolijo: mostrar las rutas completas de todos los archivos que se
395 leen, y dar información cronométrica.
398 Mostrar la garantía con que viene GNU LilyPond (¡no viene con
399 @strong{NINGUNA GARANTÍA}!).
402 @node Environment variables
403 @subsection Environment variables
407 @cindex LILYPOND_DATADIR
409 @command{lilypond} reconoce las siguientes variables de entorno:
411 @item LILYPOND_DATADIR
412 Especifica un directorio en el que los mensajes de localización y de
413 datos se buscarán de forma predeterminada. El directorio debe
414 contener subdirectorios llamados @file{ly/}, @file{ps/}, @file{tex/},
418 Selecciona el idioma de los mensajes de advertencia.
420 @item LILYPOND_GC_YIELD
421 Con esta variable se puede ajustar la huella y el desempeño de
422 memoria. Es un porcentaje que ajusta el comportamiento de la
423 administración de memoria. Con valores más altos, el programa usa más
424 memoria; con valores más bajos, usa más tiempo de CPU. El valor
425 predeterminado es @code{70}.
431 @section Error messages
433 @cindex error, mensajes de
434 @cindex mensajes de error
436 Pueden aparecer distintos mensajes de error al compilar un archivo:
442 Algo tiene un aspecto sospechoso. Si estamos pidiendo algo fuera de
443 lo común, entenderemos el mensaje y podremos ignorarlo. Sin embargo,
444 las advertencias suelen indicar que algo va mal con el archivo de
449 Algo va claramente mal. El paso actual de procesamiento (análisis,
450 interpretación o formateo visual) se dará por terminado, pero el
451 siguiente paso se saltará.
456 Algo va claramente mal, y LilyPond no puede seguir. Rara vez sucede
457 esto. La causa más frecuente son las tipografías mal instaladas.
459 @item Error de Scheme
460 @cindex traza de Scheme
461 @cindex llamadas, traza de
462 @cindex Scheme, error de
463 @cindex error de Scheme
464 Los errores que ocurren al ejecutar código de Schheme se interceptan
465 por parte del intérprete de Scheme. Si se está ejecutando con las
466 opciones @code{-V} o @code{--verbose} (prolijo) entonces se imprime
467 una traza de llamadas de la función ofensiva.
469 @item Error de programación
470 @cindex error de programación
471 @cindex programación, error de
472 Ha habido algún tipo de inconsistencia interna. Estos mensajes de
473 error están orientados a ayudar a los programadores y a los
474 depuradores. Normalmente se pueden ignorar. En ocasiones aparecen en
475 cantidades tan grandes que pueden entorpecer la visión de otros
478 @item Abortado (volcado de core)
479 Esto señala un error de programación serio que ha causado la
480 interrupción abrupta del programa. Estos errores se consideran
481 críticos. Si se topa con uno, envíe un informe de fallo.
484 @cindex error, formato de los mensajes de
486 Se los errores y advertencias se pueden ligar a un punto del archivo
487 de entrada, los mensajes tienen la forma siguiente:
490 @var{archivo}:@var{línea}:@var{columna}: @var{mensaje}
491 @var{línea de entrada problemática}
494 Se inserta un salto de línea en la línea problemática para indicar la
495 columna en que se encontró el error. Por ejemplo,
498 prueba.ly:2:19: error: no es una duración: 5
503 Estas posiciones son la mejor suposición de LilyPond sobre dónde se ha
504 producido el mensaje de error, pero (por su propia naturaleza) las
505 advertencias y errores se producen cuando ocurre algo inesperado. Si
506 no ve un error en la línea que se indica del archivo de entrada, trate
507 de comprobar una o dos líneas por encima de la posición indicada.
510 @node Updating files with convert-ly
511 @section Updating with @command{convert-ly}
513 @cindex actualización de un archivo de LilyPond
515 @cindex versión de los archivos
518 La sintaxis del lenguaje de entrada de LilyPond se modifica de forma
519 habitual para simplificarla o mejorarla de distintas maneras. Como
520 efecto secundario, el intérprete de LilyPond a menudo ya no es
521 compatible con los archivos de entrada antiguos. Para poner remedio a
522 esto se puede utilizar el programa @command{convert-ly} para manejar
523 casi todos los cambios de sintaxis entre versiones de LilyPond.
525 Utiliza los enunciados @code{\version} de los archivos de entrada para
526 detectar el número de versión antiguo. En casi todos los casos, para
527 actualizar el archivo de entrada basta con ejecutar
530 convert-ly -e miarchivo.ly
534 Los usuarios de MacOS@tie{}X pueden ejecutar esta instrucción bajo el
535 menú @code{Compilar > Actualizar sintaxis}.
537 Si no hay cambios en miarchivo.ly y se crea el archivo llamado
538 miarchivo.ly.NEW, entonces miarchivo.ly ya está actualizado.
540 @subsection Command line options
542 @command{convert-ly} convierte siempre al últimmo cambio de sintaxis
543 que puede manejar. Eesto supone que el número de @code{\version} que
544 aparece en el archivo convertido suele ser más bajo que la versión del
545 propio programa @command{convert-ly}.
547 Para actualizar fragmentos de LilyPond en archivos de texinfo, use
550 convert-ly --from=... --to=... --no-version *.itely
553 Para ver los cambios en la sintaxis de LilyPond entre dos versiones,
557 convert-ly --from=... --to=... -s
560 Para actualizar muchos archivos de una vez, combine @code{convert-ly}
561 con las instrucciones estándar de UNIX. Este ejemplo actualiza todos
562 los archivos @code{.ly} del directorio actual:
565 for f in *.ly; do convert-ly -e $f; done;
568 En general, el programa se invoca de la manera siguiente:
571 convert-ly [@var{opción}]@dots{} @var{archivo}@dots{}
575 Se pueden dar las siguientes opciones:
579 Hace una edición en línea del archivo de entrada. Sobreescribe a
582 @item -f,--from=@var{versión_de_origen}
583 Establece la versión desde la que convertir. Si no aparece esta
584 opción, @command{convert-ly} tratará de adivinarla, basándose en el
585 enunciado @code{\version} del archivo.
587 @item -n,--no-version
588 Normalmente @command{convert-ly} añade un indicador @code{\version} a
589 la salida. La especificación de esta opción lo suprime.
591 @item -s, --show-rules
592 Mostrar todas las conversiones conocidas y salir.
594 @item --to=@var{versión_final}
595 Fijar la versión de destino de la conversión. De forma predeterminada
596 se convierte a la última versión disponible.
599 Imprimir la ayuda de la utilización.
604 * Problems with convert-ly::
608 @node Problems with convert-ly
609 @subsection Problems with @code{convert-ly}
611 No se manejan todos los cambios en el lenguaje. S´olo se puede
612 especificar una opción de salida. La actualización automática de
613 Scheme y los interfaces Scheme de LilyPond es bastante improbable;
614 prepárese para trucar el código de Scheme a mano.
617 Hay algunas cosas que convert-ly no puede manejar. He aquí una lista
618 de aquellas limitaciones que han dado lugar a protestas de la
621 Se ha escogido esta estructura de informe de fallo porque convert-ly
622 tiene una estructura que no permite implementar de forma progresiva
623 todos los cambios necesarios. Así pues esto es sólo una lista de
624 deseos, y se incluye aquí como referencia.
627 No siempre convierte el bajo cifrado correctamente, específicamente cosas como {<
628 >}. El comentario de Mats sobre cómo solventar el problema:
629 Para poder ejecutar convert-ly
630 sobre él, primero sustituí todas las apariciones de '{<' a algo mudo como '{#'
631 y de forma similar sustituí '>}' con '&}'. Después de la conversión, pude
632 volver a cambiarlos de '{ #' a '{ <' y de '& }' a '> }'.
633 No convierte todos los marcados de texto correctamente. En sintaxis antigua,
634 se podían agrupar varios marcados entre paréntesis, p.ej.
635 -#'((bold italic) "cadena")
636 Esto se convierte incorrectamente en
637 -\markup{{\bold italic} "cadena"}
639 -\markup{\bold \italic "cadena"}
641 No maneja \partcombine
642 No hace \addlyrics => \lyricsto, esto rompe algunas partituras con varias estrofas.
644 \magnify no se cambia por \fontsize.
645 - \magnify #m => \fontsize #f, donde f = 6ln(m)/ln(2)
646 remove-tag no se cambia.
647 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
648 first-page-number no se cambia.
649 - first-page-number no => print-first-page-number = ##f
650 Los saltos de línea en las cadenas de cabecera no se convierten.
651 - \\\\ como salto de línea en las cadenas de \header => \markup \center-align <
652 "Primera línea" "Segunda línea" >
653 Los terminadores de crescendo y decrescendo no se convierten.
657 \turnOff (usado en \set Staff.VoltaBracket = \turnOff) no se convierte
660 \markup{ \center-align <{ ... }> } se tendría que convertir en:
661 \markup{ \center-align {\line { ... }} }
662 pero ahora, falta el \line.
664 Los caracteres especiales de LaTeX como $~$ en el texto no se convierten a UTF8.
666 \score{} ahora debe empezar con una expresión musical. Cualquier otra cosa
667 (en particular, \header{}) debe ir después de la música.
672 @section Reporting bugs
674 @cindex bugs (fallos)
675 @cindex fallos (bugs)
676 @cindex informes de fallo
678 Si tiene una entrada que produce una interrupción abrupta o una salida
679 errónea, entonces eso es un bug (fallo). Hay una lista de los fallos
680 actuales en nuestro rastreador de fallos de Google Code:
682 @uref{http://code.google.com/p/lilypond/issues/list}
684 Si descubre un error que no está en la lista, le rogramos que envíe un
685 informe del fallo siguiendo las instrucciones que aparecen en
687 @uref{http://lilypond.org/web/devel/participating/bugs}
689 Le rogamos, asimismo, que para los informes prepare y envíe ejemplos
690 mínimos de los fallos. No tenemos los recursos para investigar
691 informes que no sean lo más pequeños posible.