Hlavní navigace

Texinfo: ako na dokumentáciu (2)

Stanislav Kuchár

V dnešním pokračování seriálu o systému Texinfo se podíváme na jeho další funkce a možnosti demonstrované na příkladu, který se (narozdíl od toho v minulé části, který byl pro snadné pochopení velmi jednoduchý) více blíží skutečnosti.

Keďže vonku vládnu tropické horúčavy a naše počítače aj napriek tomu produkujú teplo, ktoré zväčša vychádza navnivoč (ak nerátame tú kopu užitočných informácií, ktoré poslušne prežujú), nechal som sa inšpirovať a pripravil som takýto príkladík. Na ňom si ukážeme trochu dlhšiu, reálnejšiu dokumentáciu (v porovnaní s tou minulou).

Podobne ako minule, riadky sú očíslované. Píšte ich bez čísel a zátvoriek na začiatku riadku. Náš pieckový príklad má, tak ako všetky Texinfo súbory 6 častí.

1. Hlavička

V samotnej hlavičke, (4) až (7), toho moc nového nie je.

Ale hneď za ňou je malý a užitočný trik. Ak chceme použiť nejaké klúčové slovo: meno programu, autora, či dátum vzniku dokumentácie na viacerých miestach, nemusíme ho zakaždým vypisovať. Stačí ho len definovať niekde na začiatku, priradiť mu nejaké klúčové slovo a v potom sa naň odkazovať. Takto si uľahčíme život, keď bude treba napríklad zmeniť číslo verzie v celej dokumentácii.

Skratky si definuje pred hneď za hlavičkou. Príklady definícií skratiek v tvare @set SKRATKA text sú na riadkoch (8) až (14).

2. Zhrnutie a Copyright pre info súbor

Tu máme hneď niekoľko príkladov použitia skratiek: (17) až (21), (25) až (30), atď. vo forme  @value{SKRATKA}.

Keby sme napríklad išli písať o programe Ventilátor (a nie Piecka), tak by to šlo celkom rýchlo: prepísaním obsahu skratky PROGRAM na riadku (14). Ale koho by v takomto teple zaujímal ventilátor, taká piecka to vám je vec…

Nový príkaz @* (17), ukončí riadok; nasledujúci text pôjde na začiatok ďalšieho riadku.

3. Titulná strana a Copyright pre výstup na tlačiareň

Novinkou v tejto časti je príkaz @page (31), ktorý ukončí aktuálnu stránku.

Zarovnanie textu vpravo zabezpečí prikaz @flushright (33), ukončený na (36)  @end flushright.

4. Hlavný uzol a menu

Top uzol (43) dostal okrem nasledovníka (prvá kapitola Popis), aj predchodcu a vyšší uzol (dir). To sú ukazovatele na zoznam všetkých info súborov, aby sme mohli zaradiť tento dokument do zoznamu.

@menu 

5. Telo

Tu sa nachádzajú všetky kapitoly a podkapitoly resp. sekcieô dokument; je delený na logické celky. Je teda rozumné najskôr popremýšľať aké časti má dokument mať a ako a ako ich zoradiť, aby na seba nadväzovali.

Každá kapitola, ktorá obsahuje sekcie (hierarchicky nižšie celky) má na konci prvej stránky zoznam týchto sekcií. Kapitola Popis (66), (67) obsahuje 2 sekcie, ktoré sú vylistované na riadkoch (74) až (77).

Na riadkoch (81) až (93) je príklad listu, ktorý má za odrážky bodky  @bullet

Formátovací príkaz @noindent (116) potlačí odsadenie, ktoré sa zvyčajne vkladá na začiatku nového odstavca.

Na riadkoch (118) až (129) je dvojstĺpcová tabuľka pre prepínače príkazového riadku. (Jednotlivé položky sú dosť dlhé a tak sú usporiadané do riadkov a nie vedľa seba.) Tabuľka sa začína príkazom @table @samp, čo znamená, že prvá položka tabuľky je ukážka (sample), možno použiť aj ostatné vyznačovacie príkazy: @code, @key, @file, atď. ako je to vidno v druhej tabuľke (138) až (144), kde je použitý príkaz  @kbd.

Ak píšete dokumentáciu pre open-source projekt, môžete si skopírovať riadky (145) až (163). Na nich sa nachádza štandardná GPL licencia verzia 2.

6. Záver

Záver neprináša žiadne novoty. Nachádza sa tam len zvyčajný index. Je plnený príkazmi @cindex, ktoré sú roztrúsené po celom dokumente: (72), (73), (85), (86), atď.

Odkazy

Na odkazy medzi uzlami (sekciami, kapitolami, a pod.) slúžia referencie. Najpoužívanejšia je @xref{uzol}. Najjednoduchší príklad je na riadku (169), kde sa odkazujeme na kapitolu Copyright. Týmto príkazom sa vždy začína veta.

Ak chceme bližšie vysvetliť, k čomu vedie takáto referencia, môžeme pripojiť vysvetľujúci text, ako na riadku (71).

Ak je odkaz v zátvorkách, použije sa forma @pxref (p ako parenthesis) na riadku (133).

Slovenčina/Čeština

Ako správne upozornil Pavel Hofman, TeX robil šarapatu s našimi národnými znakmi pri vytváraní výstupu pre tlačiareň (aspoň vidno, kto si to naozaj vyskúšal :). Jeho riešenie je elegenatnejšie ako to čo som používal doteraz, takže ho hneď použijeme.

Úvodné riadky (1) až (3) nastavia slovenské prostredie. Ak na riadku (1) nahradíme slovak slovom czech, nastaví sa české prostredie (delenie slov, úvodzovky, formát dátumu, atď.)

Kompilácia do PostScriptu bude potom vyzerať takto:

export TEX=csplain
texi2dvi piecka.texinfo
dvips -o piecka.ps piecka.dvi

Inštalácia info súboru

Súčasťou Texinfo je aj program install-info. Pomocou neho pridáme našu piecku k ostatným info súborom.

Na to však potrebujeme popis, ktorý sa nachádza na riadkoch (38) až (41). Riadok (38) je určenie kategórie – ak máme množstvo info súborov, aby sa v nich dalo podľa niečoho orietovať. Zbytok tvorí definícia položky, ktorá chceme pridať do dir súboru (zoznamu všetkých info súborov). Tieto parametre možno zadať aj z príkazového riadku.

Skompilujeme info súbor, ako obyčajne
makeinfo piecka.texinfo
skopírujeme ho do adresára pre info súbory /usr/local/info (Ak vytvárate program, ktorý budete distribuovať, to pravé miesto je /usr/info)
cp piecka.info /usr/local/info
presunieme sa do adresára /usr/local/info
cd /usr/local/info
a pridáme piecku k zoznamu.
install-info –infodir=/usr/lo­cal/info piecka.info

Linky

Našli jste v článku chybu?