Documentation/es/usage/updating.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
   2
   3 @ignore
   4     Translation of GIT committish: b381556a3132e765159edc75107b31259dbf5988
   5
   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..
   9 @end ignore
  10
  11 @c \version "2.16.0"
  12
  13
  14 @node Actualizar ficheros con convert-ly
  15 @chapter Actualizar ficheros con @command{convert-ly}
  16 @translationof Updating files with convert-ly
  17
  18 @cindex actualización de un archivo de LilyPond
  19 @cindex convert-ly
  20
  21 La sintaxis del lenguaje de entrada de LilyPond se modifica de
  22 forma habitual para simplificarla o mejorarla de distintas
  23 maneras.  Como efecto secundario, el intérprete de LilyPond a
  24 menudo ya no es compatible con los archivos de entrada antiguos.
  25 Para poner remedio a esto se puede utilizar el programa
  26 @command{convert-ly} para actualizar archivos a nuevas versiones
  27 de LilyPond.
  28
  29 @menu
  30 * ¿Por qué cambia la sintaxis?::
  31 * Invocar convert-ly::
  32 * Opciones de la línea de órdenes para convert-ly::
  33 * Problemas con convert-ly::
  34 * Conversiones manuales::
  35 @end menu
  36
  37
  38 @node ¿Por qué cambia la sintaxis?
  39 @section ¿Por qué cambia la sintaxis?
  40 @translationof Why does the syntax change?
  41
  42 @cindex convert-ly
  43 @cindex actualizar archivos de entrada antiguos
  44
  45 La sintaxis de la entrada de LilyPond cambia de manera ocasional.  A
  46 medida que el propio LilyPond mejora, la sintaxis (el lenguaje de la
  47 entrada) se modifica en consonancia.  A veces estos cambios se hacen
  48 para conseguir que la entrada sea más fácil de leer y escribir, y
  49 otras veces estos cambios son para dar cabida a nuevas funcionalidades
  50 de LilyPond.
  51
  52 Por ejemplo, se supone que todos los nombres de las propiedades de
  53 @code{\paper} y de @code{\layout} están escritos en la dorma
  54 @code{primero-segundo-tercero}.  Sin embargo, en la versión 2.11.60,
  55 observamos que la propiedad @code{printallheaders} no seguía esta
  56 convención.  ¿Deberíamos dejarla como está (confundiendo a los nuevos
  57 usuarios que tienen que tratar con un formato de entrada
  58 inconsistente), o cambiarla (fastidiando a los usuarios con
  59 experiencia que tienen partituras antiguas)?  En este caso, decidimos
  60 cambiar el nombre a @code{print-all-headers}.  Afortunadamente, este
  61 cambio se puede automatizar con nuestra herramienta
  62 @command{convert-ly}.
  63
  64 Sin embargo, lamentablemente @command{convert-ly} no puede tratar
  65 todos los cambios en la entrada.  Por ejemplo, en la versión 2.4 y
  66 anteriores de LilyPond, los acentos y las letras no inglesas se
  67 introducían utilizando LaTeX: por ejemplo, @code{No\"el} (que
  68 significa @q{Navidad} en francés).  En LilyPond 2.6 y siguientes,
  69 el carácter especial @code{ë} debe introducirse directamente en el
  70 archivo de LilyPond como un carácter UTF-8.  @command{convert-ly}
  71 no puede cambiar todos los caracteres especiales de LaTeX a
  72 caracteres de UTF-8; tendrá que actualizar manualmente sus
  73 archivos de LilyPond antiguos.
  74
  75 Las reglas de conversión de @command{convert-ly} funcionan usando
  76 correspondencia y sustitución de patrones de texto en lugar de una
  77 comprensión profunda de la sintaxis de LilyPond.  Esto tiene
  78 varias consecuencias:
  79 @itemize @bullet
  80 @item
  81 El buen funcionamiento de la conversión depende de la calidad de
  82 cada conjunto de reglas que se aplican y de la complejidad del
  83 cambio correspondiente.  A veces las conversiones pueden necesitar
  84 correcciones manuales, por lo que la versión antigua debiera
  85 conservarse a efectos de comparación.
  86 @item
  87 Solamente son posibles las conversiones a formatos más nuevos: no
  88 existe ningún conjunto de reglas para la desactualización.  Así
  89 pues, la copia principal de trabajo de un archivo de LilyPond
  90 solamente se debe actualizar cuando ya no hay necesidad de seguir
  91 manteniendo versiones antiguas de LilyPond.  Los sistemas de
  92 control de versiones como el Git pueden ser de gran ayuda para
  93 realizar el mantenimiento de varias versiones de los mismos
  94 archivos.
  95 @item
  96 Los propios programas LilyPond y Scheme son bastante robustos
  97 frente a los espacios añadidos y suprimidos de manera
  98 @qq{creativa}, pero las reglas utilizadas por @command{convert-ly}
  99 tienden a hacer ciertas suposiciones de estilo.  Lo mejor que
 100 puede hacerse es seguir el estilo que se usa en los manuales para
 101 hacer actualizaciones indoloras, especialmente porque los propios
 102 manuales se actualizan usando @command{convert-ly}.
 103 @end itemize
 104
 105 @node Invocar convert-ly
 106 @section Invocar @command{convert-ly}
 107 @translationof Invoking convert-ly
 108
 109 @command{convert-ly} utiliza los enunciados @code{\version} de los
 110 archivos de entrada para detectar el número de versión antiguo.  En
 111 casi todos los casos, para actualizar el archivo de entrada basta con
 112 ejecutar
 113
 114 @example
 115 convert-ly -e miarchivo.ly
 116 @end example
 117
 118 @noindent
 119 dentro del directorio que contiene el archivo.  Con esto se actualiza
 120 @file{miarchivo.ly} @emph{in situ} y se preserva el archivo original
 121 @file{miarchivo.ly~}.
 122
 123 @warning{@command{convert-ly} siempre convierte hasta el último cambio
 124 de sintaxis que es capaz de manejar.  Esto significa que el número de
 125 @code{\version} que aparece en el archivo convertido suele ser
 126 inferior al número de versión del propio programa
 127 @command{convert-ly}.}
 128
 129 Para convertir de una vez todos los archivos de entrada que hay en un
 130 directorio, use
 131
 132 @example
 133 convert-ly -e *.ly
 134 @end example
 135
 136 De forma alternativa, si queremos especificar un nombre distinto para
 137 el archivo actualizado, preservando el archivo original con el mismo
 138 nombre, haga
 139
 140 @example
 141 convert-ly miarchivo.ly > minuevoarchivo.ly
 142 @end example
 143
 144 El programa imprime una relación de los números de versión para los
 145 que se han hecho conversiones.  Si no se imprime ningún número de
 146 versión, el archivo ya está actualizado.
 147
 148 @noindent
 149 Los usuarios de MacOS@tie{}X pueden ejecutar esta instrucción bajo el
 150 menú @code{Compilar > Actualizar sintaxis}.
 151
 152 Los usuarios de Windows deben introducir esta instrucción en una
 153 ventana del terminal del sistema, que se encuentra por lo general bajo
 154 @code{Inicio > Accesorios > Símbolo del sistema}.
 155
 156
 157 @node Opciones de la línea de órdenes para convert-ly
 158 @section Opciones de la línea de órdenes para @command{convert-ly}
 159 @translationof Command line options for convert-ly
 160
 161 En general, el programa se invoca de la manera siguiente:
 162
 163 @example
 164 convert-ly [@var{opción}]@dots{} @var{archivo}@dots{}
 165 @end example
 166
 167 Se pueden dar las siguientes opciones:
 168
 169 @table @code
 170 @item -d, --diff-version-update
 171 incrementar la cadena @code{\version} solamente si el archivo
 172 efectivamente ha cambiado.  En tal caso, la cabecera de versión
 173 corresponderá a la versión siguiente al último cambio efectivo.
 174 Sin esa opción, la versión refleja la última conversión que se
 175 @emph{intentó} hacer.
 176
 177 @item -e, --edit
 178 Aplicar las conversiones directamente al archivo de entrada,
 179 modificándolo in situ.  El archivo original se cambia de nombre a
 180 @file{miarchivo.ly~}.  Este archivo de copia de seguridad podría
 181 ser un archivo oculto en algunos sistemas operativos.
 182
 183 @item -b, --backup-numbered
 184 Cuando se usa con la opción @samp{-e}, numerar los archivos de
 185 copia de seguridad de forma que no se sobreescriba ninguna versión
 186 anterior.  Los archivos de copia de seguridad podrían ser archivos
 187 ocultos en algunos sistemas operativos.
 188
 189 @item -f, --from=@var{versión_de_origen}
 190 Establece la versión desde la que convertir.  Si no aparece esta
 191 opción, @command{convert-ly} tratará de adivinarla, basándose en el
 192 enunciado @code{\version} del archivo.  Ejemplo: @option{--from=2.10.25}
 193
 194 @item -h, --help
 195 Imprimir la ayuda de utilización.
 196
 197 @item -l @var{loglevel}, --loglevel=@var{loglevel}
 198 Fijar el grado en que la salida es prolija a @var{loglevel}. Los
 199 valores posibles son @code{NONE} (ninguno), @code{ERROR} (errores),
 200 @code{WARNING} (advertencias), @code{PROGRESS} (avance;
 201 predeterminado) y @code{DEBUG} (depuración).
 202
 203 @item -n, --no-version
 204 Normalmente @command{convert-ly} añade un indicador @code{\version} a
 205 la salida.  La especificación de esta opción lo suprime.
 206
 207 @item -s, --show-rules
 208 Mostrar todas las conversiones conocidas y salir.
 209
 210 @item -t, --to=@var{versión_final}
 211 Fijar explícitamente a qué @code{\version} convertir, en caso
 212 contrario el valor predeterminado es la versión más actual.  Debe
 213 ser más alta que la versión de partida.
 214
 215 @example
 216 convert-ly --to=2.14.1 miarchivo.ly
 217 @end example
 218
 219 @end table
 220
 221 Para actualizar fragmentos de LilyPond en archivos de texinfo, use
 222
 223 @example
 224 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 225 @end example
 226
 227 Para ver los cambios en la sintaxis de LilyPond entre dos versiones
 228 dadas, use
 229
 230 @example
 231 convert-ly --from=@dots{} --to=@dots{} -s
 232 @end example
 233
 234
 235 @node Problemas con convert-ly
 236 @section Problemas con @code{convert-ly}
 237 @translationof Problems running convert-ly
 238
 239 Al ejecutar convert-ly en una ventana del Símbolo del Sistema bajo
 240 Windows sobre un archivo que tiene espacios en el nombre o en la ruta,
 241 es necesario encerrar todo el nombre del archivo de entrada con tres
 242 (!) pares de comillas:
 243
 244 @example
 245 convert-ly """D:/Mis partituras/Oda.ly""" > "D:/Mis partituras/nueva Oda.ly"
 246 @end example
 247
 248 Si la orden simple @command{convert-ly -e *.ly} no funciona porque la
 249 instrucción expandida se hace muy larga, en vez de ello la orden
 250 @command{convert-ly} se puede poner dentro de un bucle.  Este ejemplo
 251 para UNIX actualiza todos los documentos @file{.ly} del directorio
 252 actual
 253
 254 @example
 255 for f in *.ly; do convert-ly -e $f; done;
 256 @end example
 257
 258 En la ventana del terminal de órdenes de Windows, la instrucción
 259 correspondiente es
 260
 261 @example
 262 for %x in (*.ly) do convert-ly -e """%x"""
 263 @end example
 264
 265 No se manejan todos los cambios en el lenguaje.  Sólo se puede
 266 especificar una opción de salida.  La actualización automática de
 267 Scheme y los interfaces Scheme de LilyPond es bastante improbable;
 268 prepárese para trucar el código de Scheme a mano.
 269
 270 @node Conversiones manuales
 271 @section Conversiones manuales
 272 @translationof Manual conversions
 273
 274 En teoría, un programa como @command{convert-ly} debería poder tratar
 275 cualquier cambio en la sintaxis.  Después de todo, un programa de
 276 ordenador interpreta las versiones antigua y nueva, por lo que otro
 277 programa de ordenador podría traducir un archivo al otro@footnote{Al
 278 menos, esto es posible en cualquier archivo de LilyPond que no
 279 contenga Scheme.  Si hay Scheme dentro del archivo, contiene un
 280 lenguaje Turing-completo, y nos encontramos con el famoso @qq{Problema
 281 de la parada} en informática.}.
 282
 283 Sin embargo, el proyecto LilyPond cuenta con unos recursos limitados:
 284 no todas las conversiones se efectúan automáticamente.  A continuación
 285 aparece una lista de los problemas conocidos.
 286
 287
 288 @verbatim
 289 1.6->2.0:
 290  No siempre convierte el bajo cifrado correctamente, específicamente cosas como {<
 291 >}.  El comentario de Mats sobre cómo solventar el problema:
 292    Para poder ejecutar convert-ly
 293    sobre él, primero sustituí todas las apariciones de '{<' a algo mudo como '{#'
 294    y de forma similar sustituí '>}' con '&}'.  Después de la conversión, pude
 295    volver a cambiarlos de '{ #' a '{ <' y de '& }' a '> }'.
 296  No convierte todos los marcados de texto correctamente.  En sintaxis antigua,
 297  se podían agrupar varios marcados entre paréntesis, p.ej.
 298    -#'((bold italic) "cadena")
 299    Esto se convierte incorrectamente en
 300    -\markup{{\bold italic} "cadena"}
 301    en vez del correcto
 302    -\markup{\bold \italic "cadena"}
 303 2.0->2.2:
 304  No maneja \partcombine
 305  No hace \addlyrics => \lyricsto, esto rompe algunas partituras con varias estrofas.
 306 2.0->2.4:
 307  \magnify no se cambia por \fontsize.
 308     - \magnify #m => \fontsize #f, donde f = 6ln(m)/ln(2)
 309  remove-tag no se cambia.
 310     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 311  first-page-number no se cambia.
 312     - first-page-number no => print-first-page-number = ##f
 313  Los saltos de línea en las cadenas de cabecera no se convierten.
 314     - \\\\  como salto de línea en las cadenas de \header  => \markup \center-align <
 315       "Primera línea" "Segunda línea" >
 316  Los terminadores de crescendo y decrescendo no se convierten.
 317     - \rced => \!
 318     - \rc => \!
 319 2.2->2.4:
 320  \turnOff (usado en \set Staff.VoltaBracket = \turnOff) no se convierte
 321 adecuadamente.
 322 2.4.2->2.5.9
 323  \markup{ \center-align <{ ... }> } se tendría que convertir en:
 324  \markup{ \center-align {\line { ... }} }
 325  pero ahora, falta el \line.
 326 2.4->2.6
 327  Los caracteres especiales de LaTeX como $~$ en el texto no se convierten a UTF8.
 328 2.8
 329  \score{} ahora debe empezar con una expresión musical.  Cualquier otra cosa
 330  (en particular, \header{}) debe ir después de la música.
 331 @end verbatim
 332
 333