Doc-es: update Usage/Updating.

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

@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.