Doc-es: update Usage/Updating.

diff --git a/Documentation/es/usage/updating.itely b/Documentation/es/usage/updating.itely
index acb7b92fc517444f31bf54f1f13b940b0332fe58..da7fec6070e1fff675862b305e1d24e1605c5976 100644 (file)
--- a/Documentation/es/usage/updating.itely
+++ b/Documentation/es/usage/updating.itely
@@ -18,13 +18,16 @@
 @cindex actualización de un archivo de LilyPond
 @cindex convert-ly
 
 @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?::
 
 @menu
 * ¿Por qué cambia la sintaxis?::


@@ -42,116 +45,174 @@ de LilyPond.
 @cindex convert-ly
 @cindex actualizar archivos de entrada antiguos
 
 @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
 
 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
 @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
 @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
 @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
 
 @end itemize
 

+

 @node Invocar convert-ly
 @section Invocar @command{convert-ly}
 @translationof Invoking convert-ly
 
 @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
 
 @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}.}
 
 @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
 
 
 @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
 
 @example

-convert-ly miarchivo.ly > minuevoarchivo.ly
+convert-ly.py -e *.ly

 @end example
 
 @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
 @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
 
 
 @node Opciones de la línea de órdenes para convert-ly


@@ -171,14 +232,32 @@ Se pueden dar las siguientes opciones:
 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.
 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
 
 @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 -b, --backup-numbered
 Cuando se usa con la opción @samp{-e}, numerar los archivos de


@@ -196,13 +275,14 @@ 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
 
 @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
 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.
 
 @item -s, --show-rules
 Mostrar todas las conversiones conocidas y salir.


@@ -224,8 +304,8 @@ Para actualizar fragmentos de LilyPond en archivos de texinfo, use
 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 @end 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
+Para ver los cambios en la sintaxis de LilyPond entre dos
+versiones dadas, use

 
 @example
 convert-ly --from=@dots{} --to=@dots{} -s
 
 @example
 convert-ly --from=@dots{} --to=@dots{} -s


@@ -237,19 +317,19 @@ 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
 @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
 
 
 @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;
 
 @example
 for f in *.ly; do convert-ly -e $f; done;


@@ -267,22 +347,23 @@ 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.
 
 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
 
 @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
 
 
 @verbatim


@@ -329,5 +410,3 @@ adecuadamente.
  \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
  \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

-
-

diff --git a/Documentation/usage/updating.itely b/Documentation/usage/updating.itely
index 60b71c29debad7246ea5a7ce89fa4becabbecf8c..bad4c8c9d8104bb209bd96195b6a54dfba3ad941 100644 (file)
--- a/Documentation/usage/updating.itely
+++ b/Documentation/usage/updating.itely
@@ -19,7 +19,7 @@
 
 As LilyPond is improved, the syntax (input language) of some commands
 and functions can change.  This can result in unexpected errors,
 
 As LilyPond is improved, the syntax (input language) of some commands
 and functions can change.  This can result in unexpected errors,

-warnings or even output when input files, previously created with older
+warnings or even wrong output when input files, previously created for older

 versions of LilyPond are then used with later versions.
 
 To help with this the @command{convert-ly} command can be used to
 versions of LilyPond are then used with later versions.
 
 To help with this the @command{convert-ly} command can be used to