Slonik.sk

Texinfo: ako na dokumentáciu 1.

Určite ste už aspoň raz v živote čítali nejakú počítačovú dokumentáciu. Možno to bola man stránka, info súbor, on-line help v html alebo tlačená knižka. Ale napísali ste už dokumentáciu k svojmu produktu? Či už je to komerčný software, ktorý chcete predávať, alebo len malá užitočná utilitka, ktorá vám denno-denne uľahčuje život, a s ktorou sa chcete, v duchu open-source, podeliť so širokými masami, určite ho potrebujete zdokumentovať. A práve pre vás je tu Texinfo.

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 je už pripravený, aby sme sa naň mohli odkazovať. Riadky sú očíslované, aby sa dali ľahšie okomentovať. Do editora ich píšte bez čísel a zátvoriek na začiatku riadku.

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.

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

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

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

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.

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

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

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