Texinfo: ako na dokumentáciu

Skúsení hackeri hovoria, že zdrojový kód programu je tá najlepšia dokumentácia. To je možno pravda, ale už ste sa niekedy prehrabovali zdrojovým kódom, len aby ste zistili ako vyvolať predchádzajúci príkaz v bashi, alebo kôli tomu aby ste zistili aký má syntax select v MySQL, alebo z akých znakov sa môže skladať rule v make? Ak nepatríte medzi tých pár osvietených, veru by ste sa nahľadali…

Texinfo je dokumentačný systém z dielne GNU, ktorý z jedného zdrojového súboru dokáže vytvoriť nielen on-line dokumentáciu, ale aj výstup vhodný na tlačenie. Netreba teda prácne editovať niekoľko rozdielnych súborov: jeden pre man a druhý pre tlačiareň a každý z nich v inom jazyku. Stačí upravovať jeden súbor a zmeny sa premietnu do všetkých výstupných foriem.

Poviete si: „Zase ďalší jazyk, čo sa mám učiť?“

Určite sa to oplatí: štandardne sa z Texinfo zdrojáku produkujú info súbory a PostScriptové súbory. Info súbory ako on-line help (pozri článok o infe), PostScript pre tlač na laserovej tlačiarni. Ale je jednoduché vytvoriť PDF, HTML i RTF súbor, man stránku, či obyčajný zformátovaný text.

Stránka o dokumentácii projektov GNU hovorí o ňom toto: „Texinfo je oficiálny dokumentačný formát všetkých GNU projektov.“ Takže máte šancu sa s ním stretnetnúť naozaj často, kedže bez GNU programov si už dnes počítač ani predstaviť nevieme. Ba používa sa aj na dokumentáciu mnohých iných projektov, medzi inými napríklad MySQL.

Ako na to

Texinfo má teda očividne svoje výhody. Ako napísať dokumentáciu v Texinfo formáte? Stačí ľubovoľný textový editor: vi, joe alebo emacs. Posledne menovaný má na to dokonca aj podporný mód, ale voľba je len na vás.

Čo obsahuje tento malý zázrak, Texinfo súbor?

Nič zvláštne, len text a formátovacie príkazy Texinfa. Ako každý formátovací jazyk, i tento musel obetovať jeden znak na účely označovania formátovacích príkazov (ktoré sa nezobrazia vo výslednom texte, ale len určia vzhľad výsledného textu). Pre Texinfo bol zvolený ako formátovací znak @, za ktorým nasleduje kľučové slovo: @príkaz. Ak by vám bolo ľúto za znakom @, môžete ho do textu vložiť zdvojením:  @@.

Typický Texinfo zdrojový súbor sa skladá zo 6 častí:

1. hlavička
2. zhrnutie a copyright pre info súbor
3. titulná strana a copyright pre výstup na tlačiareň
4. hlavný uzol a menu
5. telo
6. záver.

Vidíme, že info súbor a tlačený výstup majú osobitné časti pre začiatky (2. a 3. časť). Tlačená knižka má zvyčajne zopár úvodných strán popísaných rôznymi nadpismi a u on-line manuáloch sa zväčša ide hneď k jadru veci. Najväčšia (rozsahom) je vždy 5. časť, ktorá je spoločná. Ale poďme pekne po poriadku.

Ruky na klávesnicu

Spustite si teda obľúbený editor a otvorte si nový súbor hrncek-var.texinfo, alebo ak to váš operačný systém neumožňuje,  hrncek.txi.

hrncek-var.texinfo 

Texinfo neobmedzuje dĺžku riadku. Môžeme teda písať akékoľvek dlhé riadky, pri spracovaní budú všetky riadky zalomené na patričnú dĺžku (podľa druhu výstupu). Na oddeľovanie odstavcov sa používa prázdny riadok. Prázdne riadky, ktoré sú potrebné budú očíslované, ale všetky ostatné (neočíslované) slúžia len na uľahčenie orientácie a nemusíte ich písať.

1. Hlavička

Hlavička obsahuje názov info súboru a jeho titul.

Riadky (1) až (5) sú súčasťou hlavičky.

• Riadok (1) je povinný. Je tam pre program TeX, ktorý prežuje tento súbor a vypľuje výstup pre tlačiareň (vo formáte PostScript alebo PDF).

Riadky (2) až (5) obsahujú už príkazy v jazyku Texinfo.

• Špeciálne znaky % na riadku (2) označujú začiatok hlavičky, inak je obsah tohto riadku ignorovaný vďaka príkazu @comment
• riadok (3) určí meno výsledného info súboru
• riadok (4) je titul, pre tlačenú dokumentáciu
• znaky % na riadku (5) ukončujú hlavičku.

2. Zhrnutie a Copyright pre info súbor

Táto časť nebude v tlačenej verzii, ale len v info súbore.

Zhrnutie pre info výstup tvoria riadky (6) až (11).

• Všetko, čo nasleduje za príkazom @comment (6) je ignorované; slúži len ako poznámka v texte
• príkaz @ifinfo (7), ukončený @end ifinfo na riadku (11), ohraničuje to, čo bude vidno len v info súbore
• na riadku (8) je stručné zhrnutie
• (9) je prázdny; je potrebný, pretože oddeľuje odstavce
• na (10). riadku je informácia o autorských právach tohto dokumentu v medzinárodne predpísanom formáte: COPYRIGHT ROK AUTOR.

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

Táto čast je len pre tlačenú verziu a neobjaví sa v info súbore.

Titulná strana je na riadkoch (12) až (19).

• Príkaz @titlepage na riadku (13) otvára titulnú stránku a príkaz @end titlepage na riadku (19) ju uzatvára
• na riadku (14) je názov celého dokumentu, (15) je podtitulok, kde sa zvyčajne uvádza verzia opisovaného programu
• na riadku (16) je hatlanina, ktorá asi niečo hovorí TeXpertom. Znamená to niečo takéto: „Medzi riadkami (15) a (17) sprav takú medzeru, aby bola pekne vyplnená celá stránka.“
• a na samom spodku titulnej stránky ešte uvedieme autora (17) a autorské práva (18).

Nenechajte sa odradit úvodnými časťami, ktoré vyzerajú ako zbytočnosti. Neskôr zistíte, že tieto sú takmer vždy rovnaké pre všetky dokumentácie a to podstatné práve prichádza.

4. Hlavný uzol a menu

Texinfo súbor je rozdelený do logických častí, uzlov, ktoré môžeme pre zjednodušenie chápať ako kapitoly v knihe. Kapitoly môžu byť ďalej rozdelené na menšie časti, sekcie, a tie zase na menšie časti, podsekcie. Podľa toho, koľko toho chceme čitateľovi povedať.

Obsah hlavného uzola je na riadkoch (20) až (26).

Každý uzol je označený príkazom @node. Príkaz @node obsahuje, okrem mena tohto uzla, čiarkami oddelené odkazy na uzly: nasledujúci uzol, predchádzajúci uzol, uzol o úroveň vyššie. Toto je primárny spôsob navigácie.

• Hlavný uzol je na riadku (21) a má názov Top; ostatné uzly môžu mať ľubovoľné názvy
• na riadku (22) je stručný pokec o čom je celá naša dokumentácia
• ďalší prístup k navigácii, príkaz @menu (23), ukončený na (26), obsahuje zoznam všetkých hlavných uzlov, resp. kapitol
• na riadkoch (24) a (25) sú dve položky nášho menu: Prvá kapitola a Index.

Pri prehliadaní info súboru môžeme stlačiť kdekoľvek na texte v menu Enter (alebo kliknúť myšou) a zobrazí sa nám príslušná kapitola. Meno uzla v menu (medzi * a ::) sa musí zhodovať s menom v niektorom @node príkaze.

5. Telo

Tento náš malý ukážkový dokument bude mať len jednu jedinú kapitolu.

Prvá kapitola sa rozkladá na riadkoch (27) až (50).

• Na riadku (28) je @node, ktorý hovorí, že tento uzol sa volá Prvá kapitola, jeho nasledovníkom je Index, predchodcom je Top a vyššia úroveň je tiež Top
• meno kapitoly je na riadku (29) (uzly a kapitoly nemusia byť vždy na tom istom mieste, pretože @chapter je pre tlačený dokument a @node je pre info súbor, ale zvyčajne sú úplne zhodné)
• riadky (30), (33) a (35) sú značkami pre Koncepčný index a riadky (40) a (49) sú značkami pre Programový index; tieto značky označujú miesto výskytu pojmov resp. programov ktoré sme použili
• riadky (36) a (42) sú prázdne, pretože oddeľujú odstavce
• očíslovaný list je na riadkoch (37) až (50); každá položka sa začína príkazom @item (38), (46).

Máme tu niekoľko ukážok príkazu s parameterom. Parameter je text, ktorého sa príkaz bezprostredne týka. Ten nasleduje hneď za príkazom a je uzavretý v brčkavých zátvorkách:  @príkaz{parameter}:

(32), (34) @emph{text}

slúži na zvýraznenie textu (emphasis)

(32) @file{súbor}

odlíšenie mena súboru od ostatného textu

(45) @samp{vzorka}

má široké uplatnenie: výstup programu, názorný príklad, ukážka (sample)

(39), (48) @kbd{znaky}

označuje vstup znakov z klávesnice (keyboard)

6. Záver

Záver obsahuje záverečné časti dokumentácie: indexy a obsah.

Do záveru patria riadky (51) až (57).

• Príkaz na riadku (52) označuje posledný uzol dokumentu
• (53) je kapitola, ktorá nebude očíslovaná v obsahu
• riadky (54), (55) slúžia na vygenerovanie indexu (cp znamená Koncepčný index, pg Index programov)
• riadok (56) automaticky vygeneruje obsah
• (57) @bye je povinný príkaz na ukončenie súboru.

Kompilácia

info

Súbor hrncek-var.texinfo sme úspešne napísali. Hor sa do tvorby info súboru:
makeinfo hrncek-var.texinfo

Ak to prejde bez problémov, môžeme si výsledný dokument pozrieť:
info -f hrncek-var.info

Výstup na tlačiareň

Ak máte nainštalovaný systém TeX, nebude pre vás problém vygenerovať si PostScriptový dokument:
texi2dvi hrncek-var.texinfo
dvips -o hrncek-var.ps hrncek-var.dvi

A potom si to môžete pozrieť v prezerači podľa ľubovôle (ghostview, gvu) a hodiť to na tlačiareň.

Na záver

Nabudúce si povieme ako pridať novovytvorený info súbor do zoznamu info dokumentov (dir), ako vytvoriť iné výstupy: PDF, HTML, atď.

Linky

• hrncek-var.texinfo – ak si chcete ušetriť písanie
• Texinfo – tu začnite hľadanie, ak sa nájde niečo, čo sme v tomto rýchlokurze nespomenuli
• GNU – niečo o tom, prečo „GNU + Texinfo = Veľká Láska“
• TeX, lokalizácia TeXu – pre tých, ktorí nevedia, čo je TeX, alebo LaTeX