@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.13.36"


@node A lilypond használata
@chapter A @command{lilypond} használata
@translationof Running lilypond

Ez a fejezet a LilyPond használatának technikai vonzatait részletezi.

@menu
* Egyszerű használat::
* Parancssori használat::
* Hibaüzenetek::
* Gyakori hibák::
@end menu


@node Egyszerű használat
@section Egyszerű használat
@translationof Normal usage

A legtöbb felhasználó grafikus felületről indítja a LilyPondot; ennek módját
az @rlearning{Első lecke} írja le. Kényelmi szolgáltatásokat nyújtó
szövegszerkesztők használatának leírása a saját dokumentációjukban található.


@node Parancssori használat
@section Parancssori használat
@translationof Command-line usage

Ez a szakasz a LilyPond parancssori futtatásáról tartalmaz plusz
információkat, arra az esetre, ha a programnak plusz paramétereket szeretnénk
átadni. Ráadásul bizonyos segédprogramok (mint pl. a @code{midi2ly}) csak
parancssorból érhetőek el.

@emph{Parancssor} alatt az operációs rendszer megfelelő parancssorát értjük.
A Windows-felhasználók ezt @qq{DOS-parancssor} néven, a Mac@tie{}OS@tie{}X
felhasználok @qq{Terminal} néven ismerhetik.

Az operációs rendszer parancssorának használatának leírása kívül esik a
LilyPond dokumentációjának hatáskörén; az ebben kevésbé járatos felhasználók
az operációs rendszerhez tartozó dokumentációban olvashatnak erről.

@menu
* A lilypond futtatása::
* A lilypond parancssori paraméterei::
* Környezeti változók::
@end menu

@node A lilypond futtatása
@unnumberedsubsec A @command{lilypond} futtatása
@translationof Invoking lilypond

A @command{lilypond} program a következő módon futtatható parancssorból:

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

Ha nem adunk meg kiterjesztést, az alapértelmezett @file{.ly} kiterjesztéssel
próbálkozik a LilyPond. A szabványos bemenetről való beolvasáshoz a @code{-}
karakter használandó @var{fájlnév} gyanánt.

Amikor a @file{fájlnév.ly} fájl feldolgozásra kerül, egy @file{fájlnév.ps}
és egy @file{fájlnév.pdf} fájlt kapunk kimenetként. Több fájlt is
feldolgoztathatunk egyszerre; ezek egymástól függetlenül kerülnek
feldolgozásra. @footnote{A GUILE megelőző állapota nem áll vissza feldolgozás
után, így elővigyázatosnak kell lenni, hogy ne változtassuk meg a rendszer
alapbeállításait Scheme kódból.}

Ha a @file{fájlnév.ly} több @code{\book} blokkot tartalmaz, minden blokkból
egy-egy, számozott kimeneti fájl keletkezik, @file{fájlnév.pdf},
@file{fájlnév-1.pdf}, @file{fájlnév-2.pdf} stb. formában. Az
@code{output-suffix} változó értéke fog szerepelni a fájlnév és a számozás
között. Például a következő bemeneti fájlból:

@example
#(define output-suffix "violino")
\score @{ @dots{} @}
#(define output-suffix "cello")
\score @{ @dots{} @}
@end example

@noindent
egy @file{@var{fájlnév}-violino.pdf} és egy @file{@var{fájlnév}-cello-1.pdf}
nevű fájl keletkezik.

@node A lilypond parancssori paraméterei
@unnumberedsubsec A @command{lilypond} parancssori paraméterei
@translationof Command line options for lilypond

@cindex parancssori paraméterek

A következő parancssori opciók támogatottak:

@table @code

@item -e,--evaluate=@var{kifejezés}
A Scheme @var{kifejezés} kiértékelése az @file{.ly} fájlok beolvasása előtt.
Több @code{-e} opció is megadható, ezek a megadott sorrendben lesznek
végrehajtva.

A kifejezés kiértékelése a @code{guile-user} modulban történik, így ha
definíciókat kell használni a @var{kifejezés}ben, a parancssorban a következőt
kell megadni:

@example
lilypond -e '(define-public a 42)'
@end example

@noindent
a forrásfájl elejére pedig a következőt kell beszúrni:

@example
#(use-modules (guile-user))
@end example

@item -f,--format=@var{formátum}
A kimenet formátuma. Lehetőségek: @code{ps}, @code{pdf} vagy @code{png}.

Példa: @code{lilypond -fpng @var{fájlnév}.ly}

@item -d,--define-default=@var{azonosító}=@var{érték}
Az @var{azonosító} nevű belső változó beállítása az @var{érték} Scheme
értékre. Ha az @var{érték} nincs megadva, az alapértelmezett @code{#t}
lesz a változó értéke. Egy opció kikapcsolásához a @code{no-} prefixumot
kell az azonosító elé írni, pl.

@cindex point-and-click, parancssor

@example
-dno-point-and-click
@end example

@noindent
ugyanaz, mint
@example
-dpoint-and-click='#f'
@end example

Íme pár hasznos opció:

@cindex súgó, parancssor

@table @samp
@item help
A @code{lilypond -dhelp} parancs futtatása kilistázza az összes elérhető
@code{-d} opciót.

@cindex papírméret, parancssor

@item paper-size
Az alapértelmezett papírméret beállítása.
@example
-dpaper-size=\"letter\"
@end example

@noindent
Ügyelni kell arra, hogy a méretet @code{\"} jelek közé írjuk.
@c Match " in previous line to help context-sensitive editors

@cindex biztonsági mód, parancssor

@item safe
A LilyPond futtatása biztonsági módban, megbízhatatlan bemenet esetén.

Amikor a LilyPond egy webszerveren keresztül érhető el, vagy a @code{-dsafe},
vagy a @code{--jail} opciót @b{MINDENKÉPPEN KÖTELEZŐ} megadni. A @code{-dsafe}
opcióval megelőzhető, hogy a forrásfájlban szereplő rosszindulatú Scheme kód
kárt okozzon. Például:

@quotation
@verbatim
#(system "rm -rf /")
{
  c4^#(ly:export (ly:gulp-file "/etc/passwd"))
}
@end verbatim
@end quotation

@code{-dsafe} módban a Scheme kifejezések kiértékelése egy speciális
biztonsági modulban történik. Ez a modul a GUILE @file{safe-r5rs} modulján
alapul, de a LilyPond API néhány függvényének meghívását lehetővé teszi.
Ezek a függvények a @file{scm/safe-lily.scm} fájlban találhatóak.

Ezenkívül biztonsági módban tilos az @code{\include} parancsok alkalmazása
és a \ karakter használata @TeX{} karakterláncokban.

Biztonsági módban ezenfelül nem lehetséges LilyPond változók importálása
Scheme-be.

A @code{-dsafe} mód @emph{nem} figyeli az erőforrások túlzott használatát.
Továbbra is elérhető, hogy a program tetszőlegesen hosszú ideig fusson,
például ciklikus adatstruktúrák használatával. Így ha a LilyPond publikus
webszerveren fut, a folyamat processzor- és memóriafelhasználását korlátozni
kell!

Biztonsági módban sok hasznos LilyPond kódrészlet nem fog lefordulni.
A @code{--jail} mód egy több lehetőséget biztosító alternatíva, de
előkészítése több munkát igényel.

@cindex kimeneti formátum
@item backend
A szedés kimeneti formátuma. Lehetőségek:
@table @code
@item ps
@cindex PostScript kimenet
 PostScript.

A PostScript fájlok teljes egészükben tartalmazzák a megjelenítéshez szükséges
TTF, Type1 és OTF betűkészleteket. Keleti karakterkészletek használata esetén
ez nagy fájlokhoz vezethet.

@item eps

@cindex Encapsulated PostScript
@cindex EPS (Encapsulated PostScript)

 Encapsulated PostScript.

Minden oldal külön @file{EPS} fájlba kerül, betűtípusok nélkül, valamint egy
összesített @file{EPS} fájl is létrejön, amely az összes oldalt tartalmazza
betűtípusokkal együtt.

A @command{lilypond-book} alapértelmezetten ezt a formátumot használja.

@item svg

@cindex SVG (Scalable Vector Graphics)

 SVG (Scalable Vector Graphics).

Oldalanként egy SVG fájl keletkezik, beágyazott betűtípusok nélkül.
Így megtekintésükhöz érdemes feltelepíteni a Century Schoolbook betűtípusokat.
Ezeket tartalmazza a LilyPond. Például UNIX alatt egyszerűen csak be kell
másolni ezeket a program könyvtárából (tipikusan
@file{/usr/share/lilypond/@/VERZIÓ/fonts/otf/}) a @file{~/.fonts/} könyvtárba.
Az SVG kimenet szabványos, így bármilyen, ezt a formátumot olvasni képes
programmal megnyitható.

@item scm

@cindex Scheme kiíratás

A belső Scheme rajzolóparancsok szó szerinti kiírása.

@item null

Nincs kimenet; ugyanaz a hatása, mint a @code{-dno-print-pages} opciónak.
@end table

Példa: @code{lilypond -dbackend=svg @var{fájlnév}.ly}

@item preview
@cindex előnézet, parancssor

A fejléc és az első szisztéma fog szerepelni a kimenetben.

@item print-pages
Teljes oldalak generálása, ez az alapbeállítás. A @code{-dno-print-pages}
opció a @code{-dpreview} opcióval együtt hasznos.

@end table


@item -h,--help
Összegzés az alkalmazás használatáról.

@item -H,--header=@var{mező}
A megadott fejlécmező kiírása a @file{@var{fájlnév}.@var{mező}} nevű fájlba.

@item --include, -I=@var{könyvtár}
A @var{könyvtár} hozzáadása a bemeneti fájlok keresési útvonalához.
@cindex keresési útvonal

@item -i,--init=@var{fájl}
Az inicializáló fájl beállítása a megadott @var{fájl}ra. (Alapértelmezett:
@file{init.ly}.)

@item -o,--output=@var{fájl}
Kimeneti fájl megadása. A megfelelő kiterjesztés automatikusan hozzáfűzésre
kerül (pl. @code{.pdf} PDF kimenet esetén).

@cindex PostScript kimenet

@item --ps
PostScript kimenet generálása.

@cindex Portable Network Graphics (PNG) kimenet

@item --png
Oldalanként egy-egy PNG kép létrehozása. Ez a @code{--ps} opció hatását vonja
maga után. A kép DPI-ben mért felbontása (alapértelmezett értéke 110) a
következőképpen állítható be:
@example
-dresolution=110
@end example

@cindex Portable Document Format (PDF) kimenet

@item --pdf
PDF generálása. A @code{--ps} opció hatását vonja maga után.


@item -j,--jail=@var{felhasználó},@var{csoport},@var{börtön},@var{könyvtár}
A @command{lilypond} futtatása ún. börtönben.

A @code{--jail} opció egy rugalmasabb alternatíva a @code{-dsafe} módnál abban
az esetben, amikor a LilyPond forrás megbízhatatlan forrásból származik, pl.
amikor webszerveren keresztül érhető el a LilyPond szolgáltatásként.

A @code{--jail} módban a @command{lilypond} gyökere a @var{börtön} lesz,
mielőtt a fordítási folyamat elkezdődne. Ezután a LilyPond átvált a megadott
felhasználóra, csoportra és könyvtárba. Ezáltal garantálható, hogy (legalábbis
elméletben) lehetetlen kitörni a börtönből. A @code{--jail} mód csak akkor
működik, ha a @command{lilypond} alkalmazást root felhasználóként futtatjuk.
Ez általában biztonságosan történik, pl. a @command{sudo} parancs
használatával.

A börtön előkészítése egy bonyolult folyamat, mivel biztosítani kell, hogy a
LilyPond @emph{a börtönben} mindent megtaláljon, ami a fordításhoz szükséges.
Egy tipikus előkészítés a következő lépésekből áll:

@table @asis
@item Különálló fájlrendszer létrehozása
A LilyPond számára létre kell hozni egy fájlrendszert, amelyet a biztonságos
@code{noexec}, @code{nodev} és @code{nosuid} opciókkal tudunk felcsatolni.
Így lehetetlen a LilyPondból programokat futtatni vagy közvetlenül eszközökre
írni. Ha egy külön partíció létrehozása nem kívánatos, egy elegendően nagy
fájl létrehozása és loop eszközként való használata is megfelelő.
A külön fájlrendszer azt is megelőzi, hogy a LilyPond többet írjon a lemezre,
mint amennyi megengedett.

@item Különálló felhasználó létrehozása
Egy, kevés jogosultsággal rendelkező (pl. @code{lily}/@code{lily} nevű)
felhasználó és csoport nevében kell, hogy fusson a LilyPond. Ennek a
felhasználónak csak egy könyvtárhoz lehet írási joga, amit a @var{könyvtár}
paraméterben kell megadni.

@item A börtön előkészítése
A LilyPond futásához szükséges összes fájlt be kell másolni a börtönbe,
megtartva az eredeti elérési utakat. Az egész LilyPond telepítés
(pl. a @file{/usr/share/lilypond} könyvtár tartalmának) másolása szükséges.

Ha mégis probléma lépne fel, a forrását legegyszerűbben az @command{strace}
paranccsal határolhatjuk be, amellyel meghatározható, hogy mely fájlok
hiányoznak.

@item A LilyPond futtatása
A @code{noexec} kapcsolóval csatolt börtönben lehetetlen külső programot
futtatni. Így csak olyan kimeneti formátumok érhetőek el, amelyek ezt nem
igénylik. Mint már említettük, superuser privilégiumokkal kell futtatni a
LilyPondot (amelyeket természetesen egyből elveszít), lehetőleg
@command{sudo} használatával. Ajánlott a LilyPond által elfoglalt
processzoridő korlátozása (pl. az @command{ulimit -t} parancs segítségével),
illetve a memóriafoglalásáé is.
@end table


@item -v,--version
Verzióinformáció kijelzése.

@item -V,--verbose
Bőbeszédűség bekapcsolása: az összes beolvasott fájl elérési útjának,
futásidőknek és egyéb információknak a kijelzése.

@item -w,--warranty
A GNU LilyPond garanciavállalásának kijelzése. (A LilyPond fejlesztői
@strong{SEMMIFÉLE GARANCIÁT} nem vállalnak!)
@end table

@node Környezeti változók
@unnumberedsubsec Környezeti változók
@translationof Environment variables


@cindex LANG
@cindex LILYPOND_DATADIR
@cindex LILYPOND_GC_YIELD

A @command{lilypond} a következő környezeti változókat veszi figyelembe:
@table @code
@item LILYPOND_DATADIR
Annak a könyvtárnak a megadására szolgál, ahol a LilyPond üzeneteit és
adatfájljait keresni fogja. Tartalmaznia kell a szükséges alkönyvtárakat
(@file{ly/}, @file{ps/}, @file{tex/} stb.).

@item LANG
A program kimeneti üzeneteinek nyelve.

@item LILYPOND_GC_YIELD
A program memóriaigénye és futásideje közötti finomhangolást lehet elvégezni
ezzel a változóval. Százalékos érték; minél nagyobb, annál több memóriát
használ a program, minél alacsonyabb, annál több processzoridőt. Az
alapértelmezett érték @code{70}.

@end table


@node Hibaüzenetek
@section Hibaüzenetek
@translationof Error messages

@cindex hibaüzenetek
Egy fájl fordítása során különböző hibaüzenetek jelenhetnek meg:

@table @emph

@item Figyelmeztetés
@cindex figyelmeztetés
Valami gyanúsnak tűnik. A figyelmeztetések azt jelzik, hogy valamit
nagy valószínűséggel nem úgy írt le a felhasználó, ahogy azt gondolta.
De ha tudatosan valami rendkívülit kérünk, akkor általában figyelmen kívül
hagyhatóak.

@item Hiba
@cindex hiba
Valami határozottan helytelen. A feldolgozás aktuális lépése (beolvasás,
értelmezés vagy formázás) befejeződik, de a következő lépés ki fog maradni.

@item Végzetes hiba
@cindex végzetes hiba
Olyan hiba történt, amitől a LilyPond nem tud tovább futni. Ez ritkán fordul
elő. A leggyakoribb ok a rosszul telepített betűtípusok.

@item Scheme hiba
@cindex Scheme hiba
A Scheme kód végrehajtása során előforduló hibák, amelyeket a Scheme
interpreter kap el. Ha bőbeszédű módban fut a LilyPond, akkor a hibás
függvényhez vezető hívások kiírásra kerülnek.

@item Programozási hiba
@cindex programozási hiba
Belső inkonzisztencia lépett fel. Ezek a hibaüzenetek a fejlesztőknek és
hibakeresőknek segítenek. Általában figyelmen kívül hagyhatóak. Néha olyan
nagy mennyiségben fordulnak elő, hogy nehéz tőlük észrevenni a többi kimeneti
üzenetet.

@item A futás megszakadt (core dumped)
@cindex core dumped
Kritikus hiba lépett fel, amely a program futását azonnal megszakította.
Az ilyen hibákat jelenteni kell a fejlesztőknek.
@end table

@cindex hibák formátuma
Ha a figyelmeztetések vagy hibák a bemeneti fájl egy konkrét részére
vonatkoznak, akkor az üzenet a következő formátummal bír:

@example
@var{fájlnév}:@var{sorszám}:@var{oszlopszám}: @var{üzenet}
@var{hibás sor}
@end example

A hibás soron belül a hiba helyét sortörés jelzi. Például:

@example
test.ly:2:19: error: not a duration: 5
  @{ c'4 e'
           5 g' @}
@end example

A probléma helye csak egy becslés, mely olykor pontatlan lehet, hiszen
természetüknél fogva a problémák nem várt bemenetnél lépnek fel. Ha nem
található hiba a megadott helyen, érdemes a környékén keresni.

A hibákról bővebben a @ref{Gyakori hibák} c. szakaszban olvashatunk.


@node Gyakori hibák
@section Gyakori hibák
@translationof Common errors

Az alábbi hibajelenségek gyakran előfordulnak, ugyanakkor az okuk nem mindig
egyértelmű vagy könnyen megtalálható. Ha azonban egyszer megértjük a
természetüket, gyorsan meg lehet rájuk találni a megoldást.


@menu
* A kotta nem fér ki az oldalra::
* Egy kottasorral több van a kelleténél::
* Hiba a ../ly/init.ly fájlban::
* Unbound variable % hibaüzenet::
* FT_Get_Glyph_Name hibaüzenet::
@end menu

@node A kotta nem fér ki az oldalra
@unnumberedsubsec A kotta nem fér ki az oldalra
@translationof Music runs off the page

Ha a kotta jobb oldalra @qq{lefolyik} az oldalról, vagy rendkívül össze
van sűrítve, szinte mindig hibás hanghosszúságról van szó, amely miatt egy
ütemben az utolsó hang túlnyúlik az ütemvonalom. Ez nem számít hibának, de
ha sok ilyen van egymás után, akkor a sor nem tud megtörni, mert sortörés csak
olyan ütemek végén helyezkedhet el, amelyek végén nem nyúlik túl hang.

A hibás ritmus könnyen megtalálható ütemhatár-ellenőrzésekkel: ld. a
@ruser{Bar and bar number checks} c. szakaszt.

Ha sok ilyen rendhagyó ütemre van szükség, akkor láthatatlan ütemvonalat kell
oda beszúrni, ahol a sortörés megengedett. Ennek módját a @ruser{Bar lines}
c. szakasz írja le.


@node Egy kottasorral több van a kelleténél
@unnumberedsubsec Egy kottasorral több van a kelleténél
@translationof An extra staff appears

Ha a kontextusokat nem explicite hozzuk létre a @code{\new} paranccsal,
akkor minden figyelmeztetés nélkül létrejön egy új kontextus ott, ahol olyan
parancs fordul elő, amely a létező kontextusban nem alkalmazható.
Egyszerű kottákban a kontextusok automatikus létrehozása hasznos, és a
legtöbb példa hasznát veszi ennek az egyszerűsítésnek. De olykor ez nem várt
kottasorok vagy tételek megjelenését eredményezheti. Például a következő
kódtól azt várnánk, hogy a kottasorban minden kottafej piros lesz, miközben
valójában az eredmény két kottasor, mely közül az alsóban alapértelmezett
színű, fekete kottafejek lesznek.

@lilypond[quote,verbatim,relative=2]
\override Staff.NoteHead #'color = #red
\new Staff { a }
@end lilypond

Ez azért történik, mert a @code{Staff} kontextus nem létezik az
@code{\override} parancs helyén, így létrejön, a finomhangolás pedig az így
létrehozott kottasorra fog vonatkozni, nem a @code{\new Staff} paranccsal
létrehozott kottasorra. A példa helyesen:

@lilypond[quote,verbatim,relative=2]
\new Staff {
  \override Staff.NoteHead #'color = #red
  a
}
@end lilypond

Másik példánkban egy @code{\relative} blokk szerepel egy @code{\repeat}
blokkon belül, ami két kottasort eredményez, amely közül a második később
kezdődik, mint az első, mert a @code{\repeat} parancs hatására két
@code{\relative} blokk keletkezik, amik implicit módon létrehoznak egy-egy
@code{Staff} és @code{Voice} kontextust.

@lilypond[quote,verbatim]
\repeat unfold 2 {
  \relative c' { c d e f }
}
@end lilypond

A megoldás a @code{\repeat} és a @code{\relative} parancsok felcserélése, a
következő módon:

@lilypond[quote,verbatim]
\relative c' {
  \repeat unfold 2 { c d e f }
}
@end lilypond


@node Hiba a ../ly/init.ly fájlban
@unnumberedsubsec Hiba a @code{../ly/init.ly} fájlban
@translationof Apparent error in ../ly/init.ly

Különféle rejtélyes hibaüzenetek jelenhetnek meg, melyek a
@file{../ly/init.ly} fájlban található szintaktikai hibára utalnak, ha a
forrásfájl nem jól formált, például nem egyezik a nyitó és csukó kapcsos
zárójelek vagy idézőjelek száma.

A leggyakoribb hiba a hiányzó @code{@}} karakter egy blokk, pl. @code{\score}} blokk
végén. A megoldás kézenfekvő: ellenőrizni kell, hogy minden kapcsos zárójelnek
megvan-e a párja. A @rlearning{Hogyan működnek a LilyPond bemeneti fájlok?}
lecke írja le a forrásfájlok helyes szerkezetét. Egy olyan szövegszerkesztő
használatával, mely kiemeli a zárójelpárokat, elkerülhetőek az ilyen hibák.

Egy másik gyakori ok az, hogy nincs szóköz a dalszöveg utolsó szótagja és a
dalszöveg blokk záró kapcsos zárójele között. Enélkül az elválasztás nélkül a
kapcsos zárójel a szótag részének számít. Emellett @emph{minden} kapcsos
zárójel körül érdemes szóközt vagy sortörést hagyni. A jelenség magyarázata a
@ruser{Lyrics explained} c. szakaszban olvasható.

A hiba akkor is előfordulhat, amikor egy záró idézőjel (@code{"}) hiányzik.
@c keep "-matching straight in fancy editors
Ebben az esetben a hiba egy közeli sorban jelentkezik. A pár nélküli idézőjel
általában néhány sorral feljebb található.

@node Unbound variable % hibaüzenet
@unnumberedsubsec @code{Unbound variable %} hibaüzenet
@translationof Error message Unbound variable %

Ez a hiba akkor fordul elő (egy @qq{GUILE signaled an error ...} hibaüzenettel
együtt), amikor a LilyPondba ágyazott Scheme kód @emph{LilyPond} formátumú
megjegyzést tartalmaz @emph{Scheme} formátumú helyett.

A LilyPondban a megjegyzések százalékjellel (@code{%}) kezdődnek, és nem
használhatóak Scheme kódon belül. A Scheme kódban a megjegyzések
pontosvesszővel (@code{;}) kezdődnek.

@node FT_Get_Glyph_Name hibaüzenet
@unnumberedsubsec @code{FT_Get_Glyph_Name} hibaüzenet
@translationof Error message FT_Get_Glyph_Name

Ez a hiba azt jelzi, hogy a bemeneti fájl egy nem ASCII karaktert tartalmaz,
ugyanakkor nem UTF-8 karakterkódolással lett elmentve. Részletekért ld. a
@ruser{Text encoding} c. szakaszt.