Documentation/ca/usage/updating.itely

   1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: ca -*-
   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 Actualització de fitxers amb convert-ly
  15 @chapter Actualització de fitxers amb @command{convert-ly}
  16 @translationof Updating files with convert-ly
  17
  18 @cindex actualització d'un fitxer del LilyPond
  19 @cindex convert-ly
  20
  21 La sintaxi del llenguatge d'entrada del LilyPond es modifica de
  22 forma habitual per a simplificar-la o millorar-la de diferents
  23 maneres. Com a efecte secundari, l'intèrpret del LilyPond sovint
  24 ja no és compatible amb els fitxers d'entrada antics.  Per posar
  25 remei a això es pot utilitzar el programa @command{convert-ly} per
  26 actualitzar fitxers a versions més noves del LilyPond.
  27
  28 @menu
  29 * Perquè canvia la sintaxi?::
  30 * Invocació de convert-ly::
  31 * Opcions de la línia d'ordres per a convert-ly::
  32 * Problemes amb convert-ly::
  33 * Conversions manuals::
  34 @end menu
  35
  36
  37 @node Perquè canvia la sintaxi?
  38 @section Perquè canvia la sintaxi?
  39 @translationof Why does the syntax change?
  40
  41 @cindex convert-ly
  42 @cindex actualització de fitxers d'entrada antics
  43
  44 La sintaxi de l'entrada del LilyPond canvia de manera ocasional.
  45 A mesura que el propi LilyPond millora,  la sintaxi (el llenguatge
  46 de l'entrada) es modifica en consonància.  A vegades aquests
  47 canvis es fan per aconseguir que l'entrada sigui més fàcil de
  48 llegir i escriure, i d'altres vegades aquests canvis són per
  49 donar cabuda a noves funcionalitats del LilyPond.
  50
  51 Per exemple, se suposa que tots els noms de les propietats de
  52 @code{\paper} i de @code{\layout} estan escrits sota la norma
  53 @code{primer-segon-tercer}.  Tot i així, a la versió 2.11.60,
  54 observem que la propietat @code{printallheaders} no seguia aquesta
  55 convenció.  Hauríem de deixar-la tal com està (confonent als nous
  56 usuaris que han de tractar amb un format d'entrada inconsistent),
  57 o canviar-la (empipant als usuaris amb experiència que tenen
  58 partitures antigues)?  En aquest cas, vam decidir canviar el nom a
  59 @code{print-all-headers}.  Afortunadament, aquest
  60 canvi es pot automatitzar amb la nostra eina
  61 @command{convert-ly}.
  62
  63 Tanmateix, lamentablement @command{convert-ly} no pot tractar tots
  64 els canvis d'entrada.  Per exemple, a la versió 2.4 i anteriors de
  65 LilyPond els accents i les lletres no angleses s'introdueixen
  66 utilitzant el LaTeX: per exemple @code{No\"el} (que significa
  67 @q{Nadal} en francès).  Al LilyPond 2.6 i següents el caràcter
  68 especial @code{ë} s'ha d'introduir directament al fitxer del
  69 LilyPond com un caràcter UTF-8.  @command{convert-ly} no pot
  70 canviar tots els caràcters especials del LaTeX a caràcters de
  71 UTF-8: haureu d'actualitzar manualment els vostres fitxers del
  72 LilyPond antics.
  73
  74 Les regles de conversió de @command{convert-ly} funcionen usant
  75 correspondència i substitució de patrons de text enlloc d'una
  76 comprensió profunda de la sintaxi del LilyPond.  Això té diverses
  77 conseqüències:
  78 @itemize @bullet
  79 @item
  80 El bon funcionament de la conversió depèn de la qualitat de cada
  81 conjunt de regles que s'apliquen i de la complexitat del canvi
  82 corresponent.  A vegades les conversions poden necessitar
  83 correccions manuals, per la qual cosa la versió antiga hauria de
  84 conservar-se a efectes de comparació.
  85 @item
  86 Solament són possibles les conversions de formats més nous: no hi
  87 ha cap conjunt de regles per a la desactualització.  Així doncs,
  88 la còpia principal de treball d'un fitxer del LilyPond solament
  89 s'ha d'actualitzar quan ja no hi ha necessitat de seguir mantenint
  90 versions antigues del LilyPond.  Els sistemes de control de
  91 versions com ara el Git poden ser de gran ajuda per realitzar el
  92 manteniment de diverses versions dels mateixos fitxers.
  93 @item
  94 Els propis programes del LilyPond i de l'Scheme són força robustos
  95 enfront als espais afegits i suprimits de manera @qq{creativa},
  96 però les regles utilitzades per @command{convert-ly} tendeixen a
  97 fer certes suposicions d'estil.  El millor que pot fer-se és
  98 seguir l'estil que s'usa als manuals per fer actualitzacions
  99 indolores, especialment perquè els propis manuals s'actualitzen
 100 usant @command{convert-ly}.
 101 @end itemize
 102
 103 @node Invocació de convert-ly
 104 @section Invocació de @command{convert-ly}
 105 @translationof Invoking convert-ly
 106
 107 @command{convert-ly} utilitza el enunciats @code{\version} dels
 108 fitxers d'entrada per detectar el número de versió antic.  En
 109 gairebé tots els casos, per actualitzar el fitxer d'entrada sols
 110 cal executar
 111
 112 @example
 113 convert-ly -e elmeufitxer.ly
 114 @end example
 115
 116 @noindent
 117 dins del directori que conté el fitxer.  Amb això s'actualitza
 118 @file{elmeufitxer.ly} @emph{in situ} i es preserva el fitxer
 119 original @file{elmeufitxer.ly~}.
 120
 121 @warning{@command{convert-ly} sempre converteix fins l'últim canvi
 122 de sintaxi que és capaç de gestionar.  Això significa que el
 123 número de @code{\version} que apareix al fitxer convertit sol ser
 124 inferior al número de versió del propi programa
 125 @command{convert-ly}.}
 126
 127 Per convertir d'un cop tots els fitxers d'entrada que hi ha a un
 128 directori, useu
 129
 130 @example
 131 convert-ly -e *.ly
 132 @end example
 133
 134 De forma alternativa, si volem especificar un nom diferent per al
 135 fitxer actualitzar, preservant el fitxer original amb el mateix
 136 nom, feu
 137
 138 @example
 139 convert-ly elmeufitxer.ly > elmeunoufitxer.ly
 140 @end example
 141
 142 El programa imprimeix una relació dels números de versió per als
 143 que s'han fet conversions.  Si no s'imprimeix cap número de
 144 versió, el fitxer ja està actualitzat.
 145
 146 @noindent
 147 Els usuaris del MacOS@tie{}X poden executar aquesta instrucció sota
 148 el menú @code{Compilar > Actualitzar sintaxi}.
 149
 150 Els usuaris del Windows han d'introduir aquesta instrucció a una
 151 nova ventana del terminal del sistema, que es troba en general sota
 152 @code{Inici > Accessoris > Símbol del sistema}.
 153
 154 @node Opcions de la línia d'ordres per a convert-ly
 155 @section Opcions de la línia d'ordres per a @command{convert-ly}
 156 @translationof Command line options for convert-ly
 157
 158 En general, el programa s'invoca de la manera següent:
 159
 160 @example
 161 convert-ly [@var{opció}]@dots{} @var{fitxer}@dots{}
 162 @end example
 163
 164 Es poden donar les opcions següents:
 165
 166 @table @code
 167 @item -d, --diff-version-update
 168 Incrementa la cadena @code{\version} solament si el fitxer
 169 efectivament ha canviat.  En tal cas, la capçalera de versió
 170 correspondrà a la versió següent a l'últim canvi efectiu.  Sense
 171 aquesta opció la versió reflecteix l'última conversió que es
 172 @emph{va intentar} fer.
 173
 174 @item -e, --edit
 175 Aplica les conversions directament al fitxer d'entrada,
 176 modificant-lo in situ.  El fitxer original es canvia de nom a
 177 @file{elmeufitxer.ly~}.  Aquest fitxer de còpia de seguretat
 178 podria ser un fitxer ocult en alguns sistemes operatius.
 179
 180 @item -b, --backup-numbered
 181 Quan s'usa amb l'opció @samp{-e}, numera els fitxers de còpia de
 182 seguretat de forma que no se sobreescrigui cap versió anterior.
 183 Els fitxers de còpia de seguretat podrien ser fitxer ocults en
 184 alguns sistemes operatius.
 185
 186 @item -f, --from=@var{versió_d_origen}
 187 Estableix la versió des de la qual s'ha de convertir.  Si no
 188 apareix aquesta opció @command{convert-ly} intentarà endevinar-la,
 189 bastant-se en la instrucció @code{\version} del fitxer. Exemple:
 190 @option{--from=2.10.25}
 191
 192 @item -h, --help
 193 Imprimeix l'ajuda d'utilització.
 194
 195 @item -l @var{nivellderegistre}, --loglevel=@var{nivellderegistre}
 196 Fixa el grau en el qual la sortida és detallada a
 197 @var{nivellderegistre}.  Els valors possibles són @code{NONE}
 198 (cap), @code{ERROR} (errors), @code{WARNING} (advertiments),
 199 @code{PROGRESS} (avenç;predeterminat) i @code{DEBUG} (depuració).
 200
 201 @item -n, --no-version
 202 Normalment @command{convert-ly} afegeix un indicador
 203 @code{\version} a la sortida.  L'especificació d'aquesta opció el
 204 suprimeix.
 205
 206 @item -s, --show-rules
 207 Mostra totes les conversions conegudes i surt.
 208
 209 @item -t, --to=@var{versió_final}
 210 Fixa explícitament a quina @code{\version} convertir, en cas
 211 contrari el valor predeterminat és la versió més actual.  Ha de
 212 ser més alta que la versió de partida.
 213
 214 @example
 215 convert-ly --to=2.14.1 elmeufitxer.ly
 216 @end example
 217
 218 @end table
 219
 220 Per actualitzar fragments del LilyPond en fitxer de texinfo, useu
 221
 222 @example
 223 convert-ly --from=@dots{} --to=@dots{} --no-version *.itely
 224 @end example
 225
 226 Per veure els canvis en la sintaxi del LilyPond entre dues
 227 versions donades, useu
 228
 229 @example
 230 convert-ly --from=@dots{} --to=@dots{} -s
 231 @end example
 232
 233
 234 @node Problemes amb convert-ly
 235 @section Problemes amb @code{convert-ly}
 236 @translationof Problems running convert-ly
 237
 238 En executar convert-ly a una finestra del Símbol de Sistema sota
 239 el Windows sobre un fitxer que té espais al nom o la ruta, és
 240 necessari tancar tot el nom del fitxer d'entrada amb tres (!)
 241 parelles de cometes:
 242
 243 @example
 244 convert-ly """D:/Les meves partitures/Oda.ly""" > "D:/Les meves partitures/nova Oda.ly"
 245 @end example
 246
 247 Si l'ordre simple @command{convert-ly -e *.ly} no funciona perquè
 248 la instrucció expandida es fa massa llarga, en comptes de fer això
 249 l'ordre @command{convert-ly} es pot posar dins d'un bucle.  Aquest
 250 exemple per a UNIX actualitza tots els documents @file{.ly} del
 251 directori actual
 252
 253 @example
 254 for f in *.ly; do convert-ly -e $f; done;
 255 @end example
 256
 257 A la finestra del terminal d'ordres del Windows, la instrucció
 258 corresponent és
 259
 260 @example
 261 for %x in (*.ly) do convert-ly -e """%x"""
 262 @end example
 263
 264 No es gestionen tots els canvis al llenguatge.  Sols es pot
 265 especificar una opció de sortida.   L'actualització automàtica del
 266 Scheme i les interfícies Scheme del LilyPond és força improbable;
 267 prepareu-vos per manipular el codi del Scheme a mà.
 268
 269 @node Conversions manuals
 270 @section Conversions manuals
 271 @translationof Manual conversions
 272
 273 En teoria, un programa com @command{convert-ly} hauria de poder
 274 tractar qualsevol canvi de sintaxi.  Després de tot, un programa
 275 d'ordinador interpreta les versions antiga i nova, per la qual
 276 cosa un altre programa d'ordinador podria traduir un fitxer a
 277 l'altre@footnote{Almenys això és possible en qualsevol fitxer del
 278 LilyPond que no contingui Scheme.  Si hi ha Scheme dins del
 279 fitxer, conté un llenguatge Turing-complet, i ens trobem amb el
 280 famós @qq{Problema de l'aturada}  informàtica.}.
 281
 282 Tot i així, el projecte LilyPond compta amb uns recursos limitats:
 283 no totes les conversions s'efectuen automàticament.  A continuació
 284 hi ha una llista de problemes coneguts.
 285
 286 @verbatim
 287 1.6->2.0:
 288 No sempre converteix el baix xifrat correctament, específicament
 289 coses com ara {<
 290 >}.  El comentari de Mats sobre com solucionar el
 291 problema:
 292    Per poder executar convert-ly
 293    sobre ell, primer vaig sustituir totes les aparicions de '{<' a quelcom mut com ara '{#'
 294    i de forma semblant vaig sustituir '>}' amb '&}'.  Després de la conversió, vaig poder
 295    tornar a canviar-los de '{ #' a '{ <' i de '& }' a '> }'.
 296  No converteix tot l'etiquetatge de text correctament.  En sintaxi antiga,
 297  es podien agrupar diverses etiquetes entre parèntesis, per exemple
 298    -#'((bold italic) "cadena")
 299    Això es converteix incorrectament a
 300    -\markup{{\bold italic} "cadena"}
 301    en comptes del correcte
 302    -\markup{\bold \italic "cadena"}
 303 2.0->2.2:
 304  No gestiona \partcombine
 305  No va \addlyrics => \lyricsto, això trenca algunes partitures amb diverses estrofes
 306 2.0->2.4:
 307  \magnify no es canvia per \fontsize.
 308     - \magnify #m => \fontsize #f, on f = 6ln(m)/ln(2)
 309  remove-tag no es canvia.
 310     - \applyMusic #(remove-tag '. . .) => \keepWithTag #'. . .
 311  first-page-number no es canvia.
 312     - first-page-number no => print-first-page-number = ##f
 313  Els salts de línia a les cadenes de capçalera no es converteixen.
 314     - \\\\  com salt de línia a les cadenes de \header  => \markup \center-align <
 315       "Primera línia" "Segona línia" >
 316  Els terminadors de crescendo i descrecendo no es converteixen.
 317     - \rced => \!
 318     - \rc => \!
 319 2.2->2.4:
 320  \turnOff (usat a \set Staff.VoltaBracket = \turnOff) no es converteix
 321 adequadament.
 322 2.4.2->2.5.9
 323  \markup{ \center-align <{ ... }> } s'hauria de convertir a:
 324  \markup{ \center-align {\line { ... }} }
 325  però ara, falta el \line.
 326 2.4->2.6
 327  Els caràcters especials del LaTeX com $~$ al text no es converteixen a UTF8.
 328 2.8
 329  \score{} ara ha de començar amb una expressió musical.  Qualsevol alta cosa
 330  (en particular, \header{}) ha d'anar després de la música.
 331 @end verbatim