Hlavní navigace

Texinfo: ako na dokumentáciu (3)

Stanislav Kuchár

V poslednej časti seriálu o dokumentačnom systéme Texinfo sa pozrieme na zúbok ďalším výstupným formátom, zistíme prečo sa Texinfo číta [tekinfo] a pridáme zopár tipov pre emacs.

Výstupy

Okrem výstupných formátov spomenutých v minulých častiach: info a PostScript, sa z Texinfo zdrojáku dajú získať aj iné výstupy. V nasledujúcich príkladoch použijeme piecku z minulej časti.

PDF

Na PDF potrebujeme, podobne ako pri PostScripte, nainštalovaný a poslovenčený resp. počeštený TeX:

export TEX=pdfcstex
texi2dvi piecka.texinfo

Nedajte sa zmiasť tým texi2dvi, výsledok kompilácie bude priamo PDF a nie medziprodukt DVI. Mohli by sme použit priamo:

pdfcstex piecka.texinfo

ale je výhodnejšie použiť prefíkaný skript texi2dvi, ktorý spustí TeX potrebný počet krát (niekedy musí TeX byť spustený viac krát, aby sa zaktualizovali odkazy, obsah a podobne).

pdfcstex 

ps2pdf piecka.ps
alebo
pstopdf piecka.ps

podľa toho čo máte k dispozícii.
 

HTML

Texinfo od verzie 4.0 obsahuje program makeinfo, ktorý vie okrem info súboru vypľuť aj html:

makeinfo –html piecka.texinfo

Ak máte staršiu verziu, skúste:

texi2html piecka.texinfo
 

Plain text alebo holý text

Holý sformátovaný text môže byť niekedy tiež na mieste. Ak povieme makeinfo, aby vynechal hlavičky, ktoré sú súčasťou info súboru, dostaneme obyčajný text, sformátovaný podobne ako info súbor:

makeinfo –output piecka.txt –no-headers piecka.texinfo
  

Iné

Existujú aj ďalšie formáty, ktoré sa dajú vygenerovať z Texinfo zdrojáku: nroff/troff (man stránky), RTF (Rich Text Format), atď. Ich vývoj však kôli nezáujmu odumiera.
  

Texinfo sa číta [tekinfo]

Ako to už býva zvykom u angličtiny, veci sa vyslovujú inak ako by jeden očakával: TeX sa číta [tech], Microsoft sa vyslovuje [majkrošit], MySQL sa vyslovuje [májeskjúel] a nie [májsíkvel], Linux sa vyslovuje … [linux], tí Fíni sú vždy výnimka. „Hei, puhutko Suomea?“

Aj Texinfo má svoju špeciálnu výslovnosť: [tekinfo]. Podpísala sa pod to výslovnosť slova technical [teknikl], pretože autori mali na mysli technickú dokumentáciu a taktiež typografický systém TeX, ktorý Texinfo využíva.

A ešte jeden detail, Texinfo sa vždy píše s veľkým začiatočným písmenom.
  

Emacs

Pre editor emacs bol vytvorený podporný mód, ktorý uľahčuje editovanie Texinfo zdrojákov. Neznamená to však, že Texinfo súbory musíte písať v emacse. Výber editora je celkom na vás; Texinfo súbor obsahuje len ASCII znaky, takže napísať ho môžete v akomkoľvek editore.

Ak používate emacs, tu sú najužitočnejšie texinfo-mode klávesy:

C-c C-u C-e alebo M-x texinfo-every-node-update
Vloží správne ukazovatele na Next, Prev a Up uzly. @node teda stačí písať len v tvare @node Názov časti a zbytok je dopĺňaný automaticky. Ak urobíme nejakú zmenu v štruktúre dokumentu, táto skratka opraví všetky ukazovatele uzlov, ktorých sa zmena týka.
Predpokladom k správnemu fungovaniu je, že Texinfo súbor musí byť hierarchicky usporiadaný. Kapitola obsahuje sekcie, sekcie sú tvorené podsekciami, atď.
C-c C-u C-a alebo M-x texinfo-all-menus-update
Vytvorí, alebo zaktualizuje všetky menu v celom Texinfo súbore. Vychádza z údajov v príkaze @node.
C-c C-u m alebo M-x texinfo-master-menu
Vytvorí kompletné menu v hlavnom uzle.
C-c C-s alebo M-x texinfo-show-structure
Veľmi užitočná skratka. Prehľadne zobrazí štruktúru celého dokumentu: kapitoly, ich sekcie, podsekcie…

Na záver

Ak ste sa dostali až tu, možno povedať, že s týmito základmi by ste mali teraz byť schopní napísať slušnú dokumentáciu.

Ak však plánujete niečo rozsiahlejšie, vrele vám odporúčam na ďalšie štúdium originálnu Texinfo dokumentáciu (pomôcka: skúste príkaz info texinfo), pretože nech som sa snažil akokoľvek, nepodarilo sa mi tu napchať všetko to, čo tam napísali o Texinfo na viac než 200 stranách.
  

Linky

Našli jste v článku chybu?