1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
4 Translation of GIT committish: bd8e8f0193000854fef9d3de3cc0a9f667ea8fb1
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
14 @node Actualizar ficheros con convert-ly
15 @chapter Actualizar ficheros con @command{convert-ly}
16 @translationof Updating files with convert-ly
18 @cindex actualización de un archivo de LilyPond
21 Según LilyPond va mejorando, puede cambiar la sintaxis de algunas
22 instrucciones y funcioens del lenguaje de entrada. Ello puede
23 conducir a errores inesperados, advertencias y hasta salida
24 errónea cada vez que se utilizan con la versión actual de LilyPond
25 archivos de entrada que habían sido creados para versiones
28 Como ayuda para este problema, puede usarse la herramienta
29 @command{convert-ly} para actualizar esos archivos de entrada
30 antiguos y que sigan la sintaxis nueva.
33 * ¿Por qué cambia la sintaxis?::
34 * Invocar convert-ly::
35 * Opciones de la línea de órdenes para convert-ly::
36 * Problemas con convert-ly::
37 * Conversiones manuales::
41 @node ¿Por qué cambia la sintaxis?
42 @section ¿Por qué cambia la sintaxis?
43 @translationof Why does the syntax change?
46 @cindex actualizar archivos de entrada antiguos
48 Con frecuencia, los cambios en la sintaxis se llevan a cabo para
49 hacer que la entrada sea más sencilla tanto de leer como de
50 escribir, pero en ocasiones se hacen los cambios para acomodar
51 nuevas funcionalidades o mejoras para las funciones existentes.
53 Lo ilustramos a continuación con un ejemplo real:
55 Se supone que todos los nombres de las propiedades de
56 @code{\paper} y de @code{\layout} están escritos en la forma
57 @code{primero-segundo-tercero}. Sin embargo, en la versión
58 2.11.60, observamos que la propiedad @code{printallheaders} no
59 seguía esta convención. ¿Deberíamos dejarla como está
60 (confundiendo a los nuevos usuarios que tienen que tratar con un
61 formato de entrada inconsistente), o cambiarla (fastidiando a los
62 usuarios con experiencia que tienen partituras antiguas)?
64 Se tomó la decisión de cambiar el nombre de la propiedad por
65 @code{print-all-headers}, y mediante el uso de la herramienta
66 @command{convert-ly} se dio a los usuarios existentes la
67 posibiilidad de actualizar automáticamente los archivos de entrada
68 que tenían previamente.
70 Sin embargo, el uso de la herramienta @command{convert-ly} no
71 permite tratar todos los cambios de sintaxis. En versiones de
72 LilyPond anteriores a la 2.4.2, los acentos y las letras no
73 inglesas se introducían utilizando LaTeX: por ejemplo,
74 @code{No\"el} (que significa @q{Navidad} en francés). Pero a
75 partir de LilyPond 2.6, el carácter especial @code{ë} debe
76 introducirse directamente en el archivo de LilyPond como un
77 carácter UTF-8. La herramienta @command{convert-ly} no sabe cómo
78 cambiar los caracteres especiales de LaTeX a caracteres de UTF-8;
79 tendrá que actualizar manualmente sus archivos de LilyPond
82 Las reglas de conversión de @command{convert-ly} funcionan usando
83 correspondencia y sustitución de patrones de texto en lugar de una
84 @q{comprensión} profunda de los cambios producidos en un archivo
85 dado. Esto tiene varias consecuencias:
89 El buen funcionamiento de la conversión depende de la calidad de
90 cada conjunto de reglas que se aplican y de la complejidad del
91 cambio correspondiente. A veces las conversiones pueden necesitar
92 correcciones manuales adicionales, por lo que los archivos
93 originales deberían conservarse a efectos de comparación, si es
97 Solamente son posibles las conversiones a las sintaxis más
98 recientes: no existe ningún conjunto de reglas para volver a
99 versiones más antiguas de LilyPond. Así pues, el archivo de
100 entrada solamente se debe actualizar cuando ya no se mantienen las
101 versiones antiguas de LilyPond. De nuevo, es conveniente
102 conservar, por si acaso, los archivos de entrada, quizá mediante
103 el uso de un sistema de control de versiones como el Git, que
104 puede ser de gran ayuda para realizar el mantenimiento de varias
105 versiones de los mismos archivos.
108 LilyPond es bastante robusto al procesar espacios añadidos y
109 suprimidos de manera @qq{creativa}, pero las reglas utilizadas por
110 @command{convert-ly} con frecuencia hacen ciertas suposiciones de
111 estilo. Por tanto, se recomienda seguir el estilo de la entrada
112 tal y como se usa en los manuales de LilyPond para que las
113 actualizaciones sean indoloras, especialmente porque todos los
114 ejemplos de los propios manuales se actualizan usando la
115 herramienta @command{convert-ly}.
119 @node Invocar convert-ly
120 @section Invocar @command{convert-ly}
121 @translationof Invoking convert-ly
123 La herramienta @command{convert-ly} utiliza los enunciados
124 @code{\version} del archivo de entrada para detectar el número de
125 versión antiguo. En casi todos los casos, para actualizar el
126 archivo de entrada basta con ejecutar lo siguiente:
129 convert-ly -e miarchivo.ly
133 dentro del directorio que contiene el archivo de entrada. Con
134 esto se actualiza @file{miarchivo.ly} @emph{in situ} y se preserva
135 el archivo original renombrándolo como @file{miarchivo.ly~}. Se
136 modifica también el número de @code{\version} en el archivo
137 actualizado además de la necesaria puesta al día de la sintaxis.
139 Al ejecutarse, la herramienta @command{convert-ly} imprime los
140 números de versión de las conversiones que se han hecho. Si no
141 aparece en el listado ningún número de versión para este archivo,
142 significa que ya está actualizado y que es compatible con la
143 sintaxis de la última versión de LilyPond.
145 @warning{Para cada versión nueva de LilyPond, se crea una
146 herramienta @command{convert-ly} asimismo nueva, aunque no todas y
147 cada una de las versiones de LilyPond requiere cambios en la
148 sintaxis de sus archivos de entrada a partir de la versión
149 anterior. Ello significa que la herramienta @command{convert-ly}
150 solamente convierte archivos hasta el último cambio de sintaxis
151 que tiene, lo que a su vez podría implicar que el número de
152 @code{\version} que se escribe en el archivo actualizado es, a
153 veces, anterior que la versión de la propia herramienta
154 @command{convert-ly}.}
156 Para convertir todos los archivos de entrada que hay en un solo
157 directorio, utilice lo siguiente:
163 Tanto los usuarios de Linux como los de MacOS@tie{}X pueden usar
164 la aplicación de terminal correspondiente, pero los usuarios de
165 MacOS@tie{}X pueden también ejecutar esta orden directamente desde
166 el menú @code{Compilar > Actualizar la sintaxis}.
168 Un usuario de Windows ejecutaría la instrucción:
171 convert-ly.py -e *.ly
175 escribiéndola en un terminal de línea de órdenes o @code{indicador
176 del sistema} que normalmente se encuentra bajo @code{Inicio >
177 Accessorios > Consola de órdenes} o, para los usuarios de la
178 versión 8, escribiendo en la ventana de búsqueda @q{consola de
181 Para converitr todos los archivos de entrada que residen en
182 distintos conjuntos de subdirectorios:
185 find . -name '*.ly' -exec convert-ly -e '@{@}' \;
188 Este ejemplo busca y convierte todos los archivos de entrada que
189 están en el directorio actual y en todos los directorios que están
190 dentro de él, de forma recursiva. Los archivos convertidos se
191 colocan en el mismo directorio que sus originales renombrados.
192 También debería funcionar para los usuarios de MacOS@tie{}X, si
193 bien solamente a través de la aplicación de terminal.
195 Los usuarios de Windows deben hacer lo siguiente:
198 forfiles /s /M *.ly /c "cmd /c convert-ly.py -e @@file"
201 Como alternativa, se puede indicar una ruta explícita al nivel
202 superior del directorio que contiene todos los sub-directorios que
203 contienen archivos de entrada, mediante la opción @code{/p}:
206 forfiles /s /p C:\Documentos\MisPartituras /M *.ly /c "cmd /c convert-ly.py -e @@file"
209 Si el nombre o la ruta del directorio de nivel superior contienen
210 espacios, entonces hay que poner entre comillas la ruta completa:
213 forfiles /s /p "C:\Documentos\Mis Partituras" /M *.ly /c "cmd /c convert-ly.py -e @@file"
218 @node Opciones de la línea de órdenes para convert-ly
219 @section Opciones de la línea de órdenes para @command{convert-ly}
220 @translationof Command line options for convert-ly
222 En general, el programa se invoca de la manera siguiente:
225 convert-ly [@var{opción}]@dots{} @var{archivo}@dots{}
228 Se pueden dar las siguientes opciones:
231 @item -d, --diff-version-update
232 incrementar la cadena @code{\version} solamente si el archivo
233 efectivamente ha cambiado. En tal caso, la cabecera de versión
234 corresponderá a la versión siguiente al último cambio efectivo.
235 Los números de las versiones de desarrollo se redondean hacia
236 arriba al número de la siguiente versión estable, a no ser que
237 fuera superior al número de la versión objetivo. Sin esa opción,
238 la versión refleja la última conversión que se @emph{intentó}
242 Aplicar las conversiones directamente al archivo de entrada,
243 modificándolo in situ. El archivo original se cambia de nombre a
244 @file{miarchivo.ly~}. Este archivo de copia de seguridad podría
245 ser un archivo oculto en algunos sistemas operativos. Como
246 alternativa, si queremos especificar un nombre distinto para el
247 archivo actualizado sin que la tilde curva @code{~},
248 predeterminada de la opción @code{-e}, se añada al final del
249 nombre del archivo antiguo, se puede en su lugar redirigir la
253 convert-ly miarchivo.ly > miarchivonuevo.ly
256 Los usuarios de Windows harán lo siguiente:
259 convert-ly.py miarchivo.ly > miarchivonuevo.ly
262 @item -b, --backup-numbered
263 Cuando se usa con la opción @samp{-e}, numerar los archivos de
264 copia de seguridad de forma que no se sobreescriba ninguna versión
265 anterior. Los archivos de copia de seguridad podrían ser archivos
266 ocultos en algunos sistemas operativos.
268 @item -f, --from=@var{versión_de_origen}
269 Establece la versión desde la que convertir. Si no aparece esta
270 opción, @command{convert-ly} tratará de adivinarla, basándose en el
271 enunciado @code{\version} del archivo. Ejemplo: @option{--from=2.10.25}
274 Imprimir la ayuda de utilización.
276 @item -l @var{loglevel}, --loglevel=@var{loglevel}
277 Fijar el grado en que la salida es prolija a @var{loglevel}. Los
278 valores posibles son @code{NONE} (ninguno), @code{ERROR}
279 (errores), @code{WARNING} (advertencias), @code{PROGRESS} (avance;
280 predeterminado) y @code{DEBUG} (depuración).
282 @item -n, --no-version
283 Normalmente @command{convert-ly} añade un indicador
284 @code{\version} a la salida. La especificación de esta opción lo
287 @item -s, --show-rules
288 Mostrar todas las conversiones conocidas y salir.
290 @item -t, --to=@var{versión_final}
291 Fijar explícitamente a qué @code{\version} convertir, en caso
292 contrario el valor predeterminado es la versión más actual. Debe
293 ser más alta que la versión de partida.
296 convert-ly --to=2.14.1 miarchivo.ly
301 Para actualizar fragmentos de LilyPond en archivos de texinfo, use
304 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
307 Para ver los cambios en la sintaxis de LilyPond entre dos
311 convert-ly --from=@dots{} --to=@dots{} -s
315 @node Problemas con convert-ly
316 @section Problemas con @code{convert-ly}
317 @translationof Problems running convert-ly
319 Al ejecutar convert-ly en una ventana del Símbolo del Sistema bajo
320 Windows sobre un archivo que tiene espacios en el nombre o en la
321 ruta, es necesario encerrar todo el nombre del archivo de entrada
322 con tres (!) pares de comillas:
325 convert-ly """D:/Mis partituras/Oda.ly""" > "D:/Mis partituras/nueva Oda.ly"
328 Si la orden simple @command{convert-ly -e *.ly} no funciona porque
329 la instrucción expandida se hace muy larga, en vez de ello la
330 orden @command{convert-ly} se puede poner dentro de un bucle.
331 Este ejemplo para UNIX actualiza todos los documentos @file{.ly}
332 del directorio actual
335 for f in *.ly; do convert-ly -e $f; done;
338 En la ventana del terminal de órdenes de Windows, la instrucción
342 for %x in (*.ly) do convert-ly -e """%x"""
345 No se manejan todos los cambios en el lenguaje. Sólo se puede
346 especificar una opción de salida. La actualización automática de
347 Scheme y los interfaces Scheme de LilyPond es bastante improbable;
348 prepárese para trucar el código de Scheme a mano.
351 @node Conversiones manuales
352 @section Conversiones manuales
353 @translationof Manual conversions
355 En teoría, un programa como @command{convert-ly} debería poder
356 tratar cualquier cambio en la sintaxis. Después de todo, un
357 programa de ordenador interpreta las versiones antigua y nueva,
358 por lo que otro programa de ordenador podría traducir un archivo
359 al otro@footnote{Al menos, esto es posible en cualquier archivo de
360 LilyPond que no contenga Scheme. Si hay Scheme dentro del
361 archivo, contiene un lenguaje Turing-completo, y nos encontramos
362 con el famoso @qq{Problema de la parada} en informática.}.
364 Sin embargo, el proyecto LilyPond cuenta con unos recursos
365 limitados: no todas las conversiones se efectúan automáticamente.
366 A continuación aparece una lista de los problemas conocidos.
371 No siempre convierte el bajo cifrado correctamente, específicamente cosas como {<
372 >}. El comentario de Mats sobre cómo solventar el problema:
373 Para poder ejecutar convert-ly
374 sobre él, primero sustituí todas las apariciones de '{<' a algo mudo como '{#'
375 y de forma similar sustituí '>}' con '&}'. Después de la conversión, pude
376 volver a cambiarlos de '{ #' a '{ <' y de '& }' a '> }'.
377 No convierte todos los marcados de texto correctamente. En sintaxis antigua,
378 se podían agrupar varios marcados entre paréntesis, p.ej.
379 -#'((bold italic) "cadena")
380 Esto se convierte incorrectamente en
381 -\markup{{\bold italic} "cadena"}
383 -\markup{\bold \italic "cadena"}
385 No maneja \partcombine
386 No hace \addlyrics => \lyricsto, esto rompe algunas partituras con varias estrofas.
388 \magnify no se cambia por \fontsize.
389 - \magnify #m => \fontsize #f, donde f = 6ln(m)/ln(2)
390 remove-tag no se cambia.
391 - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
392 first-page-number no se cambia.
393 - first-page-number no => print-first-page-number = ##f
394 Los saltos de línea en las cadenas de cabecera no se convierten.
395 - \\\\ como salto de línea en las cadenas de \header => \markup \center-align <
396 "Primera línea" "Segunda línea" >
397 Los terminadores de crescendo y decrescendo no se convierten.
401 \turnOff (usado en \set Staff.VoltaBracket = \turnOff) no se convierte
404 \markup{ \center-align <{ ... }> } se tendría que convertir en:
405 \markup{ \center-align {\line { ... }} }
406 pero ahora, falta el \line.
408 Los caracteres especiales de LaTeX como $~$ en el texto no se convierten a UTF8.
410 \score{} ahora debe empezar con una expresión musical. Cualquier otra cosa
411 (en particular, \header{}) debe ir después de la música.