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