Doc-es: remove duplicated section and adjust hierarchies.

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

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

@ignore
    Translation of GIT committish: 45945bd973aa9161b10e3f517902afb7ef4b4a56

    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::
* Actualizar ficheros con convert-ly::
* Informar de fallos::
@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

@cindex invocar @command{lilypond}
@cindex opciones de la línea de órdenes para @command{lilypond}
@cindex órdenes, opciones de la línea de

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

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{svg}, @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.

@table @samp
@item help
La ejecución de @code{lilypond -dhelp} imprimirá todas las opciones
@code{-d} que están disponibles.

@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

@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 (Scalable Vector Graphics)
 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

@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

@untranslated