Hlavní navigace

Texinfo: ako na dokumentáciu (2)

Stanislav Kuchár 24. 8. 2000

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?
Podnikatel.cz: Hledáte investora? Neunáhlete se

Hledáte investora? Neunáhlete se

Vitalia.cz: Paštiky plné masa ho zatím neuživí

Paštiky plné masa ho zatím neuživí

Podnikatel.cz: Přehledná titulka, průvodci, responzivita

Přehledná titulka, průvodci, responzivita

Podnikatel.cz: Alza.cz má StreetShop. Mall.cz více výdejních míst

Alza.cz má StreetShop. Mall.cz více výdejních míst

Měšec.cz: U levneELEKTRO.cz už reklamaci nevyřídíte

U levneELEKTRO.cz už reklamaci nevyřídíte

Lupa.cz: EET v e-shopech? Zdražení a horší komfort

EET v e-shopech? Zdražení a horší komfort

120na80.cz: Horní cesty dýchací. Zkuste fytofarmaka

Horní cesty dýchací. Zkuste fytofarmaka

Vitalia.cz: Baletky propagují zdravotní superpostel

Baletky propagují zdravotní superpostel

Vitalia.cz: Manželka je bio, ale na sex moc není

Manželka je bio, ale na sex moc není

DigiZone.cz: Rádio Šlágr má licenci pro digi vysílání

Rádio Šlágr má licenci pro digi vysílání

Lupa.cz: Seznam mění vedení. Pavel Zima v čele končí

Seznam mění vedení. Pavel Zima v čele končí

DigiZone.cz: Sony KD-55XD8005 s Android 6.0

Sony KD-55XD8005 s Android 6.0

Podnikatel.cz: Podnikatelům dorazí varování od BSA

Podnikatelům dorazí varování od BSA

Lupa.cz: Avast po spojení s AVG propustí 700 lidí

Avast po spojení s AVG propustí 700 lidí

Root.cz: Certifikáty zadarmo jsou horší než za peníze?

Certifikáty zadarmo jsou horší než za peníze?

Podnikatel.cz: Babiš: E-shopy z EET možná vyjmeme

Babiš: E-shopy z EET možná vyjmeme

120na80.cz: Jak oddálit Alzheimera?

Jak oddálit Alzheimera?

Podnikatel.cz: Víme první výsledky doby odezvy #EET

Víme první výsledky doby odezvy #EET

Vitalia.cz: Chtějí si léčit kvasinky. Lék je jen v Německu

Chtějí si léčit kvasinky. Lék je jen v Německu

Lupa.cz: Proč firmy málo chrání data? Chovají se logicky

Proč firmy málo chrání data? Chovají se logicky