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

@ignore
    Translation of GIT committish: ba4e7ffd01ece9dc9662a035967f5a6e438f9cf9

    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"

@c Important note: if you change this node name, be sure to update
@c the URL in the warning printed when the file fails and the
@c \version statement is outdated.

@node Updating files with convert-ly
@chapter Actualizar ficheros con @command{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 funciones del lenguaje de entrada.  Ello suele
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.


@node Why does the syntax change?
@section ¿Por qué cambia la sintaxis?

@cindex convert-ly
@cindex actualizar archivos de entrada antiguos

Con frecuencia, los cambios en la sintaxis se llevan a cabo para
hacer que el código de entrada de LilyPond sea más sencillo 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{@var{primero}-@/@var{segundo}-@/@var{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)?  Al final 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.

Desgraciadamente, el uso de la herramienta @command{convert-ly} no
permite tratar todos los cambios de sintaxis.  Por ejemplo, los
acentos y otros caracteres fuera del alfabeto inglés se escribían
usando notación de @LaTeX{} estándar en las versiones anteriores a
LilyPond 2.6; palabras como @q{Cigüeña} se tenían que introducir
como @code{Cig\"ue\~na}.  Comenzando con LilyPond 2.6, la letra
especial @samp{ü} se debe escribir directamente como carácter
codificado en UTF-8.  Dado que @command{convert-ly} no puede
convertir los caracteres especiales de @LaTeX{} a caracteres de
UTF-8, los archivos de entrada de LilyPond antiguos se tenían que
editar manualmente para efectuar la conversión.

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
@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.  Como consecuencia, los
archivos de entrada solamente se deben 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.  Para tener actualizaciones sin problemas, por tanto, se
recomienda seguir el estilo de la entrada tal y como se usa en los
manuales de LilyPond, especialmente porque todos los ejemplos de
los propios manuales se actualizan usando la herramienta
@command{convert-ly}.
@end itemize


@node Command-line preliminaries
@section Introducción a la línea de órdenes

Este y los siguientes apartados solo se ocupan del uso de
@command{convert-ly} en la consola.  Las aplicaciones gráficas
como Frescobaldi incorporan sus propias interfaces a
@command{convert-ly}.

Por @q{línea de órdenes}, nos referimos a la consola del sistema
operativo, también conocida como @q{terminal}.  Los usuarios de
Windows puede que estén más familiarizados con los términos
@q{shell del DOS} o @q{línea de comandos}.  Los usuarios de macOS
podrían estar más familiarizados con los términos @q{consola} o
@q{terminal}.

Las explicaciones sobre cómo usar esta parte del sistema operativo
se salen del ámbito de este manual; consulte la documentación
disponible en cualquier otra parte si no está familiarizado con la
línea de órdenes.

@xref{The PATH environment variable} para saber cómo preparar el
sistema operativo de forma que @command{convert-ly} se pueda usar
en la línea de órdenes sin especificar una ruta.


@subheading Configuraciones adicionales para  Windows

[Los usuarios que no son de Windows pueden saltarse esta sección;
los usuarios de Windows que ya tienen instalado un intérprete de
Python (versión 3.8 o superior) también pueden saltársela.]

@command{convert-ly} es en realidad un guion o pequeño programa de
Python llamado @file{convert-ly.py}.  Dentro del paquete de
archivos binarios de LilyPond para Windows, se ubica en el mismo
directorio que el archivo binario @file{lilypond.exe} y un
intérprete de Python, @file{python.exe}.  Suponiendo que ha
desempaquetado la versión @version{} en un directorio
@file{C:\Users\yo} y que la variable de entorno @env{PATH} está
correctamente configurada, aún sería necesario lanzar

@example
python C:\Users\yo\lilypond-@version{}\bin\convert-ly.py miarchivo.ly
@end example

@noindent
lo cual es tedioso de teclear.

Se necesitan tres pasos para permitir la omisión del intérprete
(@file{python.exe}) y de la extensión @file{.py}.@footnote{Observe
que es necesario hacer los pasos 1 y 2 usando la consola de
órdenes predeterminada, @file{cmd.exe}, no usando PowerShell.}

@enumerate
@item
En la línea de órdenes, escriba

@example
assoc .py=PythonScript
@end example

@noindent
para asociar la extensión @file{.py} con el tipo de archivo
@q{PythonScript}.

@item
Siguiendo con las órdenes, escriba

@example
ftype PythonScript=C:\Users\yo\lilypond-@version{}\bin\python.exe %1 %*
@end example

@noindent
para hacer que los archivos del tipo @q{PythonScript} se manejen
por parte del @command{python.exe} de LilyPond.  Tiene que ajustar
la ruta a la ubicación real, y ¡no olvide la parte @samp{%1 %*} al
final!

@item
Modifique la variable de entorno @env{PATHEXT} y añada @file{.py}
a las entradas que ya están presentes.  Hágalo exactamente de la
misma manera que lo hizo con @env{PATH}.

@end enumerate

Ahora cierre la consola y después ábrala de nuevo, y a
continuación pruebe si funciona @code{convert-ly --version}.


@node Invoking convert-ly
@section Invocación de @command{convert-ly}

La instrucción @command{convert-ly} usa el número de
@code{\version} que está dentro del archivo de entrada para
detectar versiones más antiguas.  En casi todos los casos es
suficiente con ejecutar

@example
convert-ly -e miarchivo.ly
@end example

@noindent
en el directorio que contiene el archivo de entrada; esto
actualiza @emph{in situ} @file{miarchivo.ly} y preserva el archivo
original cambiándole el nombre por @file{miarchivo.ly~}.  El
número de @code{\version} en el archivo de entrada actualizado,
junto a las actualizaciones de sintaxis requeridas, se cambian
también.

Cuando se ejecuta la instrucción @command{convert-ly}, emite los
números de versión de las conversiones que se han hecho.  Si en la
salida no aparece listado para ese archivo ningún número de
versión, ya está actualizado y utiliza la última versión de la
sintaxis de LilyPond.

@warning{Para cada nueva versión de LilyPond, se crea una nueva
instrucción @command{convert-ly}.  Sin embargo, no toda versión de
LilyPond requiere cambios de sintaxis para los archivos de entrada
a partir de la versión anterior.  Esto significa que la
instrucción @command{convert-ly} solo convierte los archivos de
entrada hasta los últimos cambios de sintaxis que tiene, y esto a
su vez puede significar que el número de @code{@bs{}version} que
se deja grabado en el archivo de entrada actualizado, a veces es
más antiguo que la versión de la propia instrucción
@command{convert-ly}.}

Para convertir todos los archivos de entrada que están en un solo
directorio, use

@example
convert-ly -e *.ly
@end example

@noindent
como orden de consola.  Para manejar todos los archivos de entrada
que residen en diferentes subdirectorios, pruebe

@example
find . -name '*.ly' -exec convert-ly -e '@{@}' \;
@end example

@noindent
para buscar recursivamente y convertirlos en el directorio actual
y en todos los que se encuentran dentro de él.  Los archivos
convertidos se ubicarán en el mismo directorio junto a sus
versiones originales renombradas.

En Windows, ejecute en su lugar

@example
forfiles /s /M *.ly /c "cmd /c convert-ly -e @@file"
@end example

@noindent
La instrucción @command{forfiles} también acepta una ruta
explícita al nivel superior del la carpeta que contiene todas las
subcarpetas que incluyen archivos de entrada por medio del uso de
la opción @option{/p}.

@smallexample
forfiles /s /p C:\Documents\MisPartituras /M *.ly /c "cmd /c convert-ly -e @@file"
@end smallexample

Si hay espacios dentro de la la ruta al directorio del nivel
superior, toda la ruta debe estar dentro de comillas dobles, por
ejemplo

@smallexample
forfiles /s /p "C:\Documents\Mis Partituras" /M *.ly /c "cmd /c convert-ly -e @@file"
@end smallexample


@node Command line options for convert-ly
@section Opciones de la línea de órdenes para @command{convert-ly}

En general, el programa se invoca de la manera siguiente:

@example
convert-ly [@var{opción}]@dots{} @var{archivo}@dots{}
@end example

@noindent
De manera predeterminada, @command{convert-ly} escribe los datos a
la salida estándar.

Se pueden dar las siguientes opciones:

@table @code
@item --version
Mostrar el número de versión y salir.

@item -h, --help
Mostrar la ayuda de uso y salir.

@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 sobre el archivo de entrada,
modificándolo @emph{in situ}.  Si el archivo original se llama
@file{miarchivo.ly}, se retinene una copia de seguridad con el
nombre @file{miarchivo.ly~}, es decir, se añade al final un
carácter de tilde curva.  Este archivo de copia de seguridad puede
ser un archivo oculto en algunos sistemas operativos.

Si quiere que la salida convertida se almacene bajo un nombre
distinto, redireccione la salida estándar hacia un archivo.

@example
convert-ly miarchivo.ly > miarchivonuevo.ly
@end example

@noindent
Véase también la opción @option{--backup-numbered}.

@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.  Suponiendo que el archivo de entrada se llama
@file{miarchivo.ly}, intentar almacenar la copia de seguridad en
@file{miarchivo.ly.~1~}.  Si existe, intentar en cambio
@file{myfile.ly.~2~}, etc.  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 (primer) 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{PROGRESS} (avance; predeterminado),
@code{NONE} (ninguno), @code{WARN} (advertencias), @code{ERROR}
(errores) 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 -c, --current-version
De manera predeterminada, @command{convert-ly} actualiza la cadena
@code{\version} a la versión más baja necesaria.  Si se aporta
esta opción, se usa en su lugar la versión actual de LilyPond
(@version{}).

@item -s, --show-rules
Mostrar las reglas de conversión y salir.  La cantidad de
información se puede ajustar con las opciones @option{--from} y
@option{--to}.

@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

@item -v, --verbose
Mostrar las descripciones de las reglas durante la conversión.

@item -w, --warranty
Mostrar la garantía y el copyright, y salir.

@end table

Para actualizar fragmentos de LilyPond dentro de 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 Problems running convert-ly
@section Problemas con @code{convert-ly}

Si un nombre de archivo de entrada (o de salida) contiene
espacios, es necesario encerrar el nombre entre comillas dobles.

@example
convert-ly "D:/Mis partituras/Oda.ly" > "D:/Mis partituras/nueva Oda.ly"
@end example

Si la invocación de @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

Para Windows, la instrucción correspondiente es

@example
for %x in (*.ly) do convert-ly.py -e "%x"
@end example

@noindent
en la ventana del terminal.

Como se ha visto anteriormente, no se manejan todos los cambios en
el lenguaje.  En particular, 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 Manual conversions
@section Conversiones manuales

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 código de Scheme.  En caso contrario el
archivo de LilyPond 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.
Si @command{convert-ly} no es capaz de manejar un cambio en la
sintaxis, emite una advertencia como la siguiente (sacada de la
regla de conversión 2.23.12).

@example
No he sido tan listo como para convertir la música que sigue a \fine.

Advertencia: \fine ya no fuerza el final de la música.  Si su
pieza tiene música después de \fine que quiera excluir cuando se
despliega, use \volta para excluirla.  Por favor, refiérase al
manual para más detalles, y actualice manualmente.
@end example


@node Writing code to support multiple versions
@section Escritura de código que contemple varias versiones

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:

@example
#(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 example

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:

@example
@{
  c' d' e' f'
  #(if (ly:version? = '(2 21))
       #@{ \override NoteHead.color = #red #@}
       #@{ \override NoteHead.color = #blue #@})
  g' a' b' c''
@}
@end example

@strong{Nota:} Esta función fue introducida en LilyPond 2.21.80,
por lo que no es posible hacer la comparación con versiones
anteriores a esa.
