From: Francisco Vila <paconet.org@gmail.com>
Date: Fri, 5 Feb 2016 06:56:23 +0000 (+0100)
Subject: Doc-es: update Usage/Updating.
X-Git-Tag: release/2.19.37-1~36
X-Git-Url: https://git.donarmstrong.com/lilypond.git?a=commitdiff_plain;h=bd8e8f0193000854fef9d3de3cc0a9f667ea8fb1;p=lilypond.git

Doc-es: update Usage/Updating.
---

diff --git a/Documentation/es/usage/updating.itely b/Documentation/es/usage/updating.itely
index acb7b92fc5..da7fec6070 100644
--- 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
 
-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?::
@@ -42,116 +45,174 @@ de LilyPond.
 @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
@@ -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.
-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
@@ -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
-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.
@@ -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
 
-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
@@ -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
-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;
@@ -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.
 
+
 @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
@@ -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
-
-
diff --git a/Documentation/usage/updating.itely b/Documentation/usage/updating.itely
index 60b71c29de..bad4c8c9d8 100644
--- 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,
-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