@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*- @ignore 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' Guide, node Updating translation committishes.. @end ignore @c \version "2.16.0" @node Actualizar ficheros con convert-ly @chapter Actualizar ficheros con @command{convert-ly} @translationof Updating files with convert-ly @cindex actualización de un archivo de LilyPond @cindex convert-ly 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?:: * Invocar convert-ly:: * 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 @node ¿Por qué cambia la sintaxis? @section ¿Por qué cambia la sintaxis? @translationof Why does the syntax change? @cindex convert-ly @cindex actualizar archivos de entrada 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 @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 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 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 todos los archivos de entrada que hay en un solo directorio, utilice lo siguiente: @example convert-ly -e *.ly @end example 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.py -e *.ly @end example @noindent 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 @node Opciones de la línea de órdenes para convert-ly @section Opciones de la línea de órdenes para @command{convert-ly} @translationof Command line options for convert-ly En general, el programa se invoca de la manera siguiente: @example convert-ly [@var{opción}]@dots{} @var{archivo}@dots{} @end example Se pueden dar las siguientes opciones: @table @code @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. 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: @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 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 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; 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=@dots{} --to=@dots{} --no-version *.itely @end example Para ver los cambios en la sintaxis de LilyPond entre dos versiones dadas, use @example convert-ly --from=@dots{} --to=@dots{} -s @end example @node Problemas con convert-ly @section Problemas con @code{convert-ly} @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: @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 @example for f in *.ly; do convert-ly -e $f; done; @end example En la ventana del terminal de órdenes de Windows, la instrucción correspondiente es @example for %x in (*.ly) do convert-ly -e """%x""" @end example No se manejan todos los cambios en el lenguaje. Sólo se puede especificar una opción de salida. La actualización automática de 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.}. 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 1.6->2.0: No siempre convierte el bajo cifrado correctamente, específicamente cosas como {< >}. El comentario de Mats sobre cómo solventar el problema: Para poder ejecutar convert-ly sobre él, primero sustituí todas las apariciones de '{<' a algo mudo como '{#' y de forma similar sustituí '>}' con '&}'. Después de la conversión, pude volver a cambiarlos de '{ #' a '{ <' y de '& }' a '> }'. No convierte todos los marcados de texto correctamente. En sintaxis antigua, se podían agrupar varios marcados entre paréntesis, p.ej. -#'((bold italic) "cadena") Esto se convierte incorrectamente en -\markup{{\bold italic} "cadena"} en vez del correcto -\markup{\bold \italic "cadena"} 2.0->2.2: No maneja \partcombine No hace \addlyrics => \lyricsto, esto rompe algunas partituras con varias estrofas. 2.0->2.4: \magnify no se cambia por \fontsize. - \magnify #m => \fontsize #f, donde f = 6ln(m)/ln(2) remove-tag no se cambia. - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . . first-page-number no se cambia. - first-page-number no => print-first-page-number = ##f Los saltos de línea en las cadenas de cabecera no se convierten. - \\\\ como salto de línea en las cadenas de \header => \markup \center-align < "Primera línea" "Segunda línea" > Los terminadores de crescendo y decrescendo no se convierten. - \rced => \! - \rc => \! 2.2->2.4: \turnOff (usado en \set Staff.VoltaBracket = \turnOff) no se convierte adecuadamente. 2.4.2->2.5.9 \markup{ \center-align <{ ... }> } se tendría que convertir en: \markup{ \center-align {\line { ... }} } pero ahora, falta el \line. 2.4->2.6 Los caracteres especiales de LaTeX como $~$ en el texto no se convierten a UTF8. 2.8 \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 @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.