@c -*- coding: utf-8; mode: texinfo; documentlanguage: hu -*-

@ignore
    Translation of GIT committish: b005971680bc6d01130420478dcd09bc6569de97

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.16.0"


@node A convert-ly használata
@chapter A @command{convert-ly} használata
@translationof Updating files with convert-ly

@cindex fájlok frissítése
@cindex convert-ly

A LilyPond nyelvtana rendszeresen változik, hogy egyszerűsödjön és fejlődjön.
Ennek mellékhatásaként a LilyPond olykor nem tudja értelmezni a régebbi
forrásfájlokat. Ezt az inkompatibilitást hidalja át a @command{convert-ly}
segédprogram, mely a verziók közötti nyelvváltozások legtöbbjét lekezeli.

@menu
* Miért változik a szintaxis?::
* A convert-ly futtatása::
* A convert-ly parancssori paraméterei::
* Problémák a convert-ly futtatása közben::
* Kézi frissítés::
@end menu


@node Miért változik a szintaxis?
@section Miért változik a szintaxis?
@translationof Why does the syntax change?

Ahogy a LilyPond maga fejlődik, a szintaxis (azaz a bemenet nyelve) is ennek
megfelelően változik. Ezek a változások azért mennek végbe, hogy a bemenetet
könnyebb legyen olvasni és írni, vagy a LilyPond új képességeihez igazodnak.

Például minden @code{\paper} és @code{\layout} blokkbeli tulajdonság nevében a
szavak konvenció szerint kötőjelekkel kerülnek elválasztásra. A 2.11.60-as
verzióban azonban észrevettük, hogy a @code{printallheaders} tulajdonság nem
követi ezt a konvenciót. Felmerült a kérdés: úgy hagyjuk, ahogy eddig volt
(így inkonzisztenciával megzavarva az új felhasználókat), vagy
megváltoztassuk (így arra kényszerítve a régi felhasználókat, hogy meglévő
kottáikat frissítsék)? Ebben az esetben amellett döntöttünk, hogy
megváltoztatjuk @code{print-all-headers}-re. Szerencsére ezt a változás
automatikusan kezelhető a @command{convert-ly} parancssori eszközzel.

Sajnos a @code{convert-ly} nem képes a nyelvtan minden változását lekezelni.
Például a LilyPond 2.4-es és korábbi verzióiban az ékezetes és egyéb, nem
angol ábécébe tartozó karaktereket a LaTeX-ben megszokott módszerrel kellett
megadni (pl. a francia Noël szót a következőképpen: @code{No\"el}). De a
@c keep "-matching straight in fancy editors
LilyPond 2.6-os verziója óta minden ilyen karakter, pl. az @code{ë} is
közvetlenül beleírható a bemeneti fájlba UTF-8 karakterkódolással. A
@code{convert-ly} nem képes minden LaTeX szintaxissal megadott speciális
karaktert átkonvertálni az UTF-8 megfelelőjébe; ezeket kézzel kell frissíteni.


@node A convert-ly futtatása
@section A @command{convert-ly} futtatása
@translationof Invoking convert-ly

A @command{convert-ly} a forrásfájlban található @code{\version} parancs
alapján állapítja meg a fájl verziószámát. A legtöbb esetben a forrásfájl
frissítéséhez elegendő kiadni a

@example
convert-ly -e @var{fájlnév}.ly
@end example

@noindent
parancsot abban a könyvtárban, ahol a fájl található. Ez a parancs helyben
frissíti a @code{@var{fájlnév}.ly} fájlt, az eredetit pedig megőrzi
@code{@var{fájlnév}.ly~} néven.

@warning{A @command{convert-ly} parancs alapesetben csak arra a verzióra
frissít, amelyikben a legutóbbi szintaxisváltozás történt. Így általában
a frissített fájl verziószáma kisebb lesz, mint az éppen használt programé.}

Egy könyvtárban található összes bemeneti fájl frissítéséhez a következő
parancs használható:

@example
convert-ly -e *.ly
@end example

Amennyiben az újabb fájlnak más nevet szeretnénk adni, és az eredeti fájlt
változatlanul szeretnénk hagyni, a következő parancsot adjuk ki:

@example
convert-ly @var{fájlnév}.ly > @var{újfájlnév}.ly
@end example

Futása során a program kiírja a verziószámokat, amelyekre frissítés történt.
Ha egy verziószám sincs kiírva, akkor a fájl teljesen friss.

A Mac OS@tie{}X-felhasználók ezt a parancsot a grafikus felületen is elérhetik
a @code{Compile > Update syntax} menüpontból.

A Windows-felhasználóknak ezeket a parancsokat a DOS parancssorba kell beírni,
amit tipikusan a Start menüben a @code{Programok > Kellékek > Parancssor}
kiválasztásával lehet elindítani.


@node A convert-ly parancssori paraméterei
@section A @command{convert-ly} parancssori paraméterei
@translationof Command line options for convert-ly

A program meghívása a következő módon történik:

@example
convert-ly [@var{opció}]@dots{} @var{fájlnév}@dots{}
@end example


A következő opciók adhatóak meg:

@table @code
@item -e,--edit
A fájl helyben frissítése.

@item -f,--from=@var{forrásverzió}
A forrásfájl verziójának megadása. Ha nincs megadva, a @command{convert-ly}
a fájlban található @code{\version} parancs alapján kitalálja.
Példa: @code{--from=2.10.25}

@item -n,--no-version
Alapesetben a @command{convert-ly} ellátja a kimenetét a megfelelő
@code{\version} paranccsal. Ez az opció ezt tiltja le.

@item -s, --show-rules
Nem történik frissítés, csak a frissítési szabályok kiírása.

@item --to=@var{célverzió}
Azt adja meg, hogy melyik verzióra frissüljön a fájl. Alapértéke a legfrissebb
elérhető verzió. Példa: @code{--to=2.12.2}

@item -h, --help
Segítség kiírása az alkalmazás használatához.
@end table

Texinfo fájlokban található LilyPond részletek frissítéséhez az alábbi parancs
használatos:

@example
convert-ly --from=... --to=... --no-version *.itely
@end example

A LilyPond két verziója közötti, a nyelvtanban bekövetkezett változások
megtekintéséhez pedig a következő:

@example
convert-ly --from=... --to=... -s
@end example


@node Problémák a convert-ly futtatása közben
@section Problémák a @command{convert-ly} futtatása közben
@translationof Problems running convert-ly

Amikor olyan forrásfájlt frissítünk a @command{convert-ly} segédprogrammal
Windows alatt parancssorból, amelynek elérési útja szóközt tartalmaz, a
forrásfájl elérési útját három-három (!) idézőjel közé kell írni:

@example
convert-ly """D:/Az én kottáim/Óda.ly""" > "D:/Az én kottáim/Óda - új.ly"
@end example

Ha az egyszerű @command{convert-ly -e *.ly} parancs futása meghiúsul a fájlok
nagy mennyisége miatt, a másik lehetőség a @command{convert-ly} futtatása
ciklusban. A következő, UNIX alatt használható példa minden @code{.ly} fájlt
frissít az aktuális könyvtárban:

@example
for f in *.ly; do convert-ly -e $f; done;
@end example

A Windows parancssorában a megfelelő parancs:

@example
for %x in (*.ly) do convert-ly -e """%x"""
@end example

A program nem minden változást képes kezelni.
A Scheme kód és a LilyPond Scheme felületének frissítése nem történik meg, a
Scheme kódrészleteket kézzel kell átírni.


@node Kézi frissítés
@section Kézi frissítés
@translationof Manual conversions

Ideális esetben a @command{convert-ly} minden változás kezelésére képes lenne.
Elvégre ha a régi verzió képes volt értelmezni a régi nyelvtant, az új verzió
pedig az újat, akkor elvileg létezhetne egy másik program, amelyik a kettő
közötti konverziót elvégzi@footnote{Legalábbis ez abban az esetben
lehetséges, ha a LilyPond fájl nem tartalmaz Scheme kódot. Ha viszont
tartalmaz, akkor egy Turing-teljes nyelvvel van dolgunk, és az
algoritmuselméletben jól ismert @qq{megállási problémába} ütközünk.}.

A gyakorlatban azonban a LilyPond erőforrásai korlátosak: nem minden konverzió
történik meg automatikusan. Íme az ismert problémák listája.


@verbatim
1.6 -> 2.0:
- A számozott basszus frissítése nem tökéletes, főleg a {< >} esetében.
Ez úgy kerülhető meg, hogy a '{<' karakterlánc összes előfordulását egy
ideiglenes másik karakterláncra cseréljük, pl. '{#'-re. Hasonlóképpen a
'>}' előfordulásai '&}'-re cserélendőek. A frissítés után pedig a következő
cseréket kell végrehajtani: '{ #' -> '{ <' és '& }' -> '> }'.
- A formázott szövegek frissítése sem mindig jó. Eddig zárójelekkel
csoportosítani lehetett több formázó parancsot, pl.:
   -#'((bold italic) "string")
Ez sajnos helytelenül a következővé alakul:
   -\markup{{\bold italic} "string"}
A helyes ez lenne:
   -\markup{\bold \italic "string"}

2.0 -> 2.2:
- A \partcombine frissítése nem támogatott.
- Az \addlyrics => \lyricsto frissítés nem történik meg, ez több versszakkal
rendelkező kották esetében problémát okozhat.

2.0 -> 2.4:
A következő konverziók nem támogatottak:
- \magnify #m => \fontsize #f, ahol f = 6ln(m)/ln(2))
- \applyMusic #(remove-tag '...) => \keepWithTag #'...
- first-page-number no => print-first-page-number = ##f
- "Első sor" \\\\ "Második sor" =>
  \markup \center-align < "Első sor" "Második sor" >
- \rced => \!
- \rc => \!

2.2 -> 2.4:
A \turnOff parancs (pl. a következő esetben:
\set Staff.VoltaBracket = \turnOff) frissítése helytelen.

2.4.2 -> 2.5.9
A \markup{ \center-align <{ ... }> } parancs a frissítés után
\markup{ \center-align {\line { ... }} } kellene, hogy legyen, de a \line
jelenleg hiányzik.

2.4 -> 2.6
A speciális LaTeX karakterek (pl. $~$) nem alakulnak át az UTF-8
megfelelőjükre.

2.8
A \score{} blokknak innentől kezdve egy zenei kifejezéssel kell kezdődnie.
Minden más (pl. a \header{} blokk) a zene után jöhet csak.
@end verbatim