@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 actualizar archivos a nuevas 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?::
@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 @command{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. @command{convert-ly}
-no puede cambiar todos los caracteres especiales de LaTeX a
-caracteres de UTF-8; tendrá que actualizar manualmente sus
-archivos de LilyPond antiguos.
+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
-comprensión profunda de la sintaxis de LilyPond. Esto tiene
-varias consecuencias:
+@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, por lo que la versión antigua debiera
-conservarse a efectos de comparación.
+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 formatos más nuevos: no
-existe ningún conjunto de reglas para la desactualización. Así
-pues, la copia principal de trabajo de un archivo de LilyPond
-solamente se debe actualizar cuando ya no hay necesidad de seguir
-manteniendo versiones antiguas de LilyPond. Los sistemas de
-control de versiones como el Git pueden ser de gran ayuda para
-realizar el mantenimiento de varias versiones de los mismos
-archivos.
+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
-Los propios programas LilyPond y Scheme son bastante robustos
-frente a los espacios añadidos y suprimidos de manera
-@qq{creativa}, pero las reglas utilizadas por @command{convert-ly}
-tienden a hacer ciertas suposiciones de estilo. Lo mejor que
-puede hacerse es seguir el estilo que se usa en los manuales para
-hacer actualizaciones indoloras, especialmente porque los propios
-manuales se actualizan usando @command{convert-ly}.
+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
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.
-Sin esa opción, la versión refleja la última conversión que se
-@emph{intentó} hacer.
+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. 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.
+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:
+
+@example
+convert-ly miarchivo.ly > miarchivonuevo.ly
+@end example
+
+Los usuarios de Windows harán lo siguiente:
+
+@example
+convert-ly.py miarchivo.ly > miarchivonuevo.ly
+@end example
@item -b, --backup-numbered
Cuando se usa con la opción @samp{-e}, numerar los archivos de
@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.
+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.
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=@dots{} --to=@dots{} -s
@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
\score{} ahora debe empezar con una expresión musical. Cualquier otra cosa
(en particular, \header{}) debe ir después de la música.
@end verbatim
-
-
projects / lilypond.git / commitdiff