@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@ignore
- Translation of GIT committish: 2aeac5e3815effa47427dad86d6be811c7b0d8a2
+ Translation of GIT committish: 094be7d770e887169f70249804e1e96e04a44ca5
When revising a translation, copy the HEAD committish of the
version that you are working on. For details, see the Contributors'
@cindex actualización de un archivo de LilyPond
@cindex convert-ly
-La sintaxis del lenguaje de entrada de LilyPond se modifica de forma
-habitual para simplificarla o mejorarla de distintas maneras. Como
-efecto secundario, el intérprete de LilyPond a menudo ya no es
-compatible con los archivos de entrada antiguos. Para poner remedio a
-esto se puede utilizar el programa @command{convert-ly} para manejar
-casi todos los cambios de sintaxis entre versiones de LilyPond.
+Según LilyPond va mejorando, puede cambiar la sintaxis de algunas
+instrucciones y funcioens del lenguaje de entrada. Ello puede
+conducir a errores inesperados, advertencias y hasta salida
+errónea cada vez que se utilizan con la versión actual de LilyPond
+archivos de entrada que habían sido creados para versiones
+anteriores.
+
+Como ayuda para este problema, puede usarse la herramienta
+@command{convert-ly} para actualizar esos archivos de entrada
+antiguos y que sigan la sintaxis nueva.
@menu
* ¿Por qué cambia la sintaxis?::
* Opciones de la línea de órdenes para convert-ly::
* Problemas con convert-ly::
* Conversiones manuales::
+* Escritura de código que contemple varias versiones::
@end menu
@cindex convert-ly
@cindex actualizar archivos de entrada antiguos
-La sintaxis de la entrada de LilyPond cambia de manera ocasional. A
-medida que el propio LilyPond mejora, la sintaxis (el lenguaje de la
-entrada) se modifica en consonancia. A veces estos cambios se hacen
-para conseguir que la entrada sea más fácil de leer y escribir, y
-otras veces estos cambios son para dar cabida a nuevas funcionalidades
-de LilyPond.
-
-Por ejemplo, se supone que todos los nombres de las propiedades de
-@code{\paper} y de @code{\layout} están escritos en la dorma
-@code{primero-segundo-tercero}. Sin embargo, en la versión 2.11.60,
-observamos que la propiedad @code{printallheaders} no seguía esta
-convención. ¿Deberíamos dejarla como está (confundiendo a los nuevos
-usuarios que tienen que tratar con un formato de entrada
-inconsistente), o cambiarla (fastidiando a los usuarios con
-experiencia que tienen partituras antiguas)? En este caso, decidimos
-cambiar el nombre a @code{print-all-headers}. Afortunadamente, este
-cambio se puede automatizar con nuestra herramienta
-@command{convert-ly}.
-
-Sin embargo, lamentablemente @code{convert-ly} no puede tratar todos
-los cambios en la entrada. Por ejemplo, en la versión 2.4 y
-anteriores de LilyPond, los acentos y las letras no inglesas se
-introducían utilizando LaTeX: por ejemplo, @code{No\"el} (que
-significa @q{Navidad} en francés). En LilyPond 2.6 y siguientes, el
-carácter especial @code{ë} debe introducirse directamente en el
-archivo de LilyPond como un carácter UTF-8. @code{convert-ly} no
-puede cambiar todos los caracteres especiales de LaTeX a caracteres de
-UTF-8; tendrá que actualizar manualmente sus archivos de LilyPond
+Con frecuencia, los cambios en la sintaxis se llevan a cabo para
+hacer que la entrada sea más sencilla tanto de leer como de
+escribir, pero en ocasiones se hacen los cambios para acomodar
+nuevas funcionalidades o mejoras para las funciones existentes.
+
+Lo ilustramos a continuación con un ejemplo real:
+
+Se supone que todos los nombres de las propiedades de
+@code{\paper} y de @code{\layout} están escritos en la forma
+@code{primero-segundo-tercero}. Sin embargo, en la versión
+2.11.60, observamos que la propiedad @code{printallheaders} no
+seguía esta convención. ¿Deberíamos dejarla como está
+(confundiendo a los nuevos usuarios que tienen que tratar con un
+formato de entrada inconsistente), o cambiarla (fastidiando a los
+usuarios con experiencia que tienen partituras antiguas)?
+
+Se tomó la decisión de cambiar el nombre de la propiedad por
+@code{print-all-headers}, y mediante el uso de la herramienta
+@command{convert-ly} se dio a los usuarios existentes la
+posibiilidad de actualizar automáticamente los archivos de entrada
+que tenían previamente.
+
+Sin embargo, el uso de la herramienta @command{convert-ly} no
+permite tratar todos los cambios de sintaxis. En versiones de
+LilyPond anteriores a la 2.4.2, los acentos y las letras no
+inglesas se introducían utilizando LaTeX: por ejemplo,
+@code{No\"el} (que significa @q{Navidad} en francés). Pero a
+partir de LilyPond 2.6, el carácter especial @code{ë} debe
+introducirse directamente en el archivo de LilyPond como un
+carácter UTF-8. La herramienta @command{convert-ly} no sabe cómo
+cambiar los caracteres especiales de LaTeX a caracteres de UTF-8;
+tendrá que actualizar manualmente sus archivos de LilyPond
antiguos.
+Las reglas de conversión de @command{convert-ly} funcionan usando
+correspondencia y sustitución de patrones de texto en lugar de una
+@q{comprensión} profunda de los cambios producidos en un archivo
+dado. Esto tiene varias consecuencias:
+
+@itemize @bullet
+@item
+El buen funcionamiento de la conversión depende de la calidad de
+cada conjunto de reglas que se aplican y de la complejidad del
+cambio correspondiente. A veces las conversiones pueden necesitar
+correcciones manuales adicionales, por lo que los archivos
+originales deberían conservarse a efectos de comparación, si es
+necesario.
+
+@item
+Solamente son posibles las conversiones a las sintaxis más
+recientes: no existe ningún conjunto de reglas para volver a
+versiones más antiguas de LilyPond. Así pues, el archivo de
+entrada solamente se debe actualizar cuando ya no se mantienen las
+versiones antiguas de LilyPond. De nuevo, es conveniente
+conservar, por si acaso, los archivos de entrada, quizá mediante
+el uso de un sistema de control de versiones como el Git, que
+puede ser de gran ayuda para realizar el mantenimiento de varias
+versiones de los mismos archivos.
+
+@item
+LilyPond es bastante robusto al procesar espacios añadidos y
+suprimidos de manera @qq{creativa}, pero las reglas utilizadas por
+@command{convert-ly} con frecuencia hacen ciertas suposiciones de
+estilo. Por tanto, se recomienda seguir el estilo de la entrada
+tal y como se usa en los manuales de LilyPond para que las
+actualizaciones sean indoloras, especialmente porque todos los
+ejemplos de los propios manuales se actualizan usando la
+herramienta @command{convert-ly}.
+@end itemize
+
@node Invocar convert-ly
@section Invocar @command{convert-ly}
@translationof Invoking convert-ly
-@command{convert-ly} utiliza los enunciados @code{\version} de los
-archivos de entrada para detectar el número de versión antiguo. En
-casi todos los casos, para actualizar el archivo de entrada basta con
-ejecutar
+La herramienta @command{convert-ly} utiliza los enunciados
+@code{\version} del archivo de entrada para detectar el número de
+versión antiguo. En casi todos los casos, para actualizar el
+archivo de entrada basta con ejecutar lo siguiente:
@example
convert-ly -e miarchivo.ly
@end example
@noindent
-dentro del directorio que contiene el archivo. Con esto se actualiza
-@file{miarchivo.ly} @emph{in situ} y se preserva el archivo original
-@file{miarchivo.ly~}.
-
-@warning{@command{convert-ly} siempre convierte hasta el último cambio
-de sintaxis que es capaz de manejar. Esto significa que el número de
-@code{\version} que aparece en el archivo convertido suele ser
-inferior al número de versión del propio programa
+dentro del directorio que contiene el archivo de entrada. Con
+esto se actualiza @file{miarchivo.ly} @emph{in situ} y se preserva
+el archivo original renombrándolo como @file{miarchivo.ly~}. Se
+modifica también el número de @code{\version} en el archivo
+actualizado además de la necesaria puesta al día de la sintaxis.
+
+Al ejecutarse, la herramienta @command{convert-ly} imprime los
+números de versión de las conversiones que se han hecho. Si no
+aparece en el listado ningún número de versión para este archivo,
+significa que ya está actualizado y que es compatible con la
+sintaxis de la última versión de LilyPond.
+
+@warning{Para cada versión nueva de LilyPond, se crea una
+herramienta @command{convert-ly} asimismo nueva, aunque no todas y
+cada una de las versiones de LilyPond requiere cambios en la
+sintaxis de sus archivos de entrada a partir de la versión
+anterior. Ello significa que la herramienta @command{convert-ly}
+solamente convierte archivos hasta el último cambio de sintaxis
+que tiene, lo que a su vez podría implicar que el número de
+@code{\version} que se escribe en el archivo actualizado es, a
+veces, anterior que la versión de la propia herramienta
@command{convert-ly}.}
-Para convertir de una vez todos los archivos de entrada que hay en un
-directorio, use
+Para convertir todos los archivos de entrada que hay en un solo
+directorio, utilice lo siguiente:
@example
convert-ly -e *.ly
@end example
-De forma alternativa, si queremos especificar un nombre distinto para
-el archivo actualizado, preservando el archivo original con el mismo
-nombre, haga
+Tanto los usuarios de Linux como los de MacOS@tie{}X pueden usar
+la aplicación de terminal correspondiente, pero los usuarios de
+MacOS@tie{}X pueden también ejecutar esta orden directamente desde
+el menú @code{Compilar > Actualizar la sintaxis}.
+
+Un usuario de Windows ejecutaría la instrucción:
@example
-convert-ly miarchivo.ly > minuevoarchivo.ly
+convert-ly.py -e *.ly
@end example
-El programa imprime una relación de los números de versión para los
-que se han hecho conversiones. Si no se imprime ningún número de
-versión, el archivo ya está actualizado.
-
@noindent
-Los usuarios de MacOS@tie{}X pueden ejecutar esta instrucción bajo el
-menú @code{Compilar > Actualizar sintaxis}.
+escribiéndola en un terminal de línea de órdenes o @code{indicador
+del sistema} que normalmente se encuentra bajo @code{Inicio >
+Accessorios > Consola de órdenes} o, para los usuarios de la
+versión 8, escribiendo en la ventana de búsqueda @q{consola de
+órdenes}.
+
+Para converitr todos los archivos de entrada que residen en
+distintos conjuntos de subdirectorios:
+
+@example
+find . -name '*.ly' -exec convert-ly -e '@{@}' \;
+@end example
+
+Este ejemplo busca y convierte todos los archivos de entrada que
+están en el directorio actual y en todos los directorios que están
+dentro de él, de forma recursiva. Los archivos convertidos se
+colocan en el mismo directorio que sus originales renombrados.
+También debería funcionar para los usuarios de MacOS@tie{}X, si
+bien solamente a través de la aplicación de terminal.
+
+Los usuarios de Windows deben hacer lo siguiente:
+
+@example
+forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
+
+Como alternativa, se puede indicar una ruta explícita al nivel
+superior del directorio que contiene todos los sub-directorios que
+contienen archivos de entrada, mediante la opción @code{/p}:
+
+@example
+forfiles /s /p C:\Documentos\MisPartituras /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
+
+Si el nombre o la ruta del directorio de nivel superior contienen
+espacios, entonces hay que poner entre comillas la ruta completa:
+
+@example
+forfiles /s /p "C:\Documentos\Mis Partituras" /M *.ly /c "cmd /c convert-ly.py -e @@file"
+@end example
-Los usuarios de Windows deben introducir esta instrucción en una
-ventana del terminal del sistema, que se encuentra por lo general bajo
-@code{Inicio > Accesorios > Símbolo del sistema}.
@node Opciones de la línea de órdenes para convert-ly
Se pueden dar las siguientes opciones:
@table @code
-@item -e,--edit
+@item -d, --diff-version-update
+incrementar la cadena @code{\version} solamente si el archivo
+efectivamente ha cambiado. En tal caso, la cabecera de versión
+corresponderá a la versión siguiente al último cambio efectivo.
+Los números de las versiones de desarrollo se redondean hacia
+arriba al número de la siguiente versión estable, a no ser que
+fuera superior al número de la versión objetivo. Sin esa opción,
+la versión refleja la última conversión que se @emph{intentó}
+hacer.
+
+@item -e, --edit
Aplicar las conversiones directamente al archivo de entrada,
-modificándolo in situ.
+modificándolo in situ. El archivo original se cambia de nombre a
+@file{miarchivo.ly~}. Este archivo de copia de seguridad podría
+ser un archivo oculto en algunos sistemas operativos. Como
+alternativa, si queremos especificar un nombre distinto para el
+archivo actualizado sin que la tilde curva @code{~},
+predeterminada de la opción @code{-e}, se añada al final del
+nombre del archivo antiguo, se puede en su lugar redirigir la
+entrada:
-@item -f,--from=@var{versión_de_origen}
-Establece la versión desde la que convertir. Si no aparece esta
-opción, @command{convert-ly} tratará de adivinarla, basándose en el
-enunciado @code{\version} del archivo. Ejemplo: @option{--from=2.10.25}
+@example
+convert-ly miarchivo.ly > miarchivonuevo.ly
+@end example
-@item -n,--no-version
-Normalmente @command{convert-ly} añade un indicador @code{\version} a
-la salida. La especificación de esta opción lo suprime.
+Los usuarios de Windows harán lo siguiente:
-@item -s, --show-rules
-Mostrar todas las conversiones conocidas y salir.
+@example
+convert-ly.py miarchivo.ly > miarchivonuevo.ly
+@end example
-@item --to=@var{versión_final}
-Fijar la versión de destino de la conversión. De forma predeterminada
-se convierte a la última versión disponible. Ejemplo: @option{--to=2.12.2}
+@item -b, --backup-numbered
+Cuando se usa con la opción @samp{-e}, numerar los archivos de
+copia de seguridad de forma que no se sobreescriba ninguna versión
+anterior. Los archivos de copia de seguridad podrían ser archivos
+ocultos en algunos sistemas operativos.
+
+@item -f, --from=@var{versión_de_origen}
+Establece la versión desde la que convertir. Si no aparece esta
+opción, @command{convert-ly} tratará de adivinarla, basándose en el
+enunciado @code{\version} del archivo. Ejemplo: @option{--from=2.10.25}
@item -h, --help
-Imprimir la ayuda de la utilización.
+Imprimir la ayuda de utilización.
@item -l @var{loglevel}, --loglevel=@var{loglevel}
Fijar el grado en que la salida es prolija a @var{loglevel}. Los
-valores posibles son @code{NONE} (ninguno), @code{ERROR} (errores),
-@code{WARNING} (advertencias), @code{PROGRESS} (avance;
+valores posibles son @code{NONE} (ninguno), @code{ERROR}
+(errores), @code{WARNING} (advertencias), @code{PROGRESS} (avance;
predeterminado) y @code{DEBUG} (depuración).
+@item -n, --no-version
+Normalmente @command{convert-ly} añade un indicador
+@code{\version} a la salida. La especificación de esta opción lo
+suprime.
+
+@item -s, --show-rules
+Mostrar todas las conversiones conocidas y salir.
+
+@item -t, --to=@var{versión_final}
+Fijar explícitamente a qué @code{\version} convertir, en caso
+contrario el valor predeterminado es la versión más actual. Debe
+ser más alta que la versión de partida.
+
+@example
+convert-ly --to=2.14.1 miarchivo.ly
+@end example
+
@end table
Para actualizar fragmentos de LilyPond en archivos de texinfo, use
@example
-convert-ly --from=... --to=... --no-version *.itely
+convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
@end example
-Para ver los cambios en la sintaxis de LilyPond entre dos versiones
-dadas, use
+Para ver los cambios en la sintaxis de LilyPond entre dos
+versiones dadas, use
@example
-convert-ly --from=... --to=... -s
+convert-ly --from=@dots{} --to=@dots{} -s
@end example
@translationof Problems running convert-ly
Al ejecutar convert-ly en una ventana del Símbolo del Sistema bajo
-Windows sobre un archivo que tiene espacios en el nombre o en la ruta,
-es necesario encerrar todo el nombre del archivo de entrada con tres
-(!) pares de comillas:
+Windows sobre un archivo que tiene espacios en el nombre o en la
+ruta, es necesario encerrar todo el nombre del archivo de entrada
+con tres (!) pares de comillas:
@example
convert-ly """D:/Mis partituras/Oda.ly""" > "D:/Mis partituras/nueva Oda.ly"
@end example
-Si la orden simple @command{convert-ly -e *.ly} no funciona porque la
-instrucción expandida se hace muy larga, en vez de ello la orden
-@command{convert-ly} se puede poner dentro de un bucle. Este ejemplo
-para UNIX actualiza todos los documentos @file{.ly} del directorio
-actual
+Si la orden simple @command{convert-ly -e *.ly} no funciona porque
+la instrucción expandida se hace muy larga, en vez de ello la
+orden @command{convert-ly} se puede poner dentro de un bucle.
+Este ejemplo para UNIX actualiza todos los documentos @file{.ly}
+del directorio actual
@example
for f in *.ly; do convert-ly -e $f; done;
Scheme y los interfaces Scheme de LilyPond es bastante improbable;
prepárese para trucar el código de Scheme a mano.
+
@node Conversiones manuales
@section Conversiones manuales
@translationof Manual conversions
-En teoría, un programa como @command{convert-ly} debería poder tratar
-cualquier cambio en la sintaxis. Después de todo, un programa de
-ordenador interpreta las versiones antigua y nueva, por lo que otro
-programa de ordenador podría traducir un archivo al otro@footnote{Al
-menos, esto es posible en cualquier archivo de LilyPond que no
-contenga Scheme. Si hay Scheme dentro del archivo, contiene un
-lenguaje Turing-completo, y nos encontramos con el famoso @qq{Problema
-de la parada} en informática.}.
+En teoría, un programa como @command{convert-ly} debería poder
+tratar cualquier cambio en la sintaxis. Después de todo, un
+programa de ordenador interpreta las versiones antigua y nueva,
+por lo que otro programa de ordenador podría traducir un archivo
+al otro@footnote{Al menos, esto es posible en cualquier archivo de
+LilyPond que no contenga Scheme. Si hay Scheme dentro del
+archivo, contiene un lenguaje Turing-completo, y nos encontramos
+con el famoso @qq{Problema de la parada} en informática.}.
-Sin embargo, el proyecto LilyPond cuenta con unos recursos limitados:
-no todas las conversiones se efectúan automáticamente. A continuación
-aparece una lista de los problemas conocidos.
+Sin embargo, el proyecto LilyPond cuenta con unos recursos
+limitados: no todas las conversiones se efectúan automáticamente.
+A continuación aparece una lista de los problemas conocidos.
@verbatim
(en particular, \header{}) debe ir después de la música.
@end verbatim
+@node Escritura de código que contemple varias versiones
+@section Escritura de código que contemple varias versiones
+@translationof Writing code to support multiple versions
+
+En ciertos casos, especialmente al escribir código de
+@emph{bibliotecas}, es deseable dar apoyo a más de una versión de
+LilyPond, por encima de los cambios de sintaxis que rompen con la
+práctica anterior. Para hacerlo, se pueden envolver porciones de
+código alternativas dentro de expresiones condicionales que
+dependen de la versión de LilyPond que se está ejecutando
+actualmente. La función de Scheme @code{ly:version?} admite un
+operador de comparación @var{op} y una versión de referencia
+@var{ver} que se pasa como una lista de enteros con un máximo de
+tres elementos. Se ignoran los elementos que faltan, de forma que
+@code{'(2 20)} equivale a @emph{cualquier} versión de la línea de
+2.20. Son posibles construcciones como las siguientes:
+
+@verbatim
+#(cond
+ ((ly:version? > '(2 20))
+ (ly:message "Esto es código para LilyPond posterior a 2.20"))
+ ((ly:version? = '(2 19 57))
+ (ly:message "Esto solamente se ejecuta con LilyPond 2.19.57"))
+ (else (ly:message "Esto se ejecuta en cualquier otra versión")))
+@end verbatim
+
+Por lo general, esto se encontrará integrado dentro de funciones
+de biblioteca que permitan usar más de un tipo de sintaxis
+alternativas, pero también es posible usar la comparación
+directamente dentro de la música como en el ejemplo siguiente:
+
+@verbatim
+{
+ c' d' e' f'
+ #(if (ly:version? = '(2 21))
+ #{ \override NoteHead.color = #red #}
+ #{ \override NoteHead.color = #blue #})
+ g' a' b' c''
+}
+@end verbatim
+@strong{Nota:} Esta función fue introducida en LilyPond 2.19.57,
+por lo que no es posible hacer la comparación con versiones
+anteriores a esa.