Pomocí znalostí získaných v předchozím díle AsciiDoc: Vytvořte si z jednoho zdroje HTML nebo PDF dokument můžete snadno začít vytvářet a strukturovat i relativně rozsáhlejší dokumenty. Protože bych nechtěl přepisovat dokumentaci jazyka, která je kvalitně (a za pomoci AsciiDoc) zpracována na oficiálních stránkách projektu, pojďme se nyní podívat na několik postupů, které by se vám při vytváření dokumentu v AsciiDoc mohly hodit. Nebudou všechny, to by se nám sem nevešlo, ale doufám, že se vám budou hodit stejně jako mně.
Poznámky a různé vsuvky
Podobně jako v každé dobré učebnici, v řadě blogů nebo stejně jako u nás na portálu, potřebuje každý čas od času vypíchnout nějakou tu informaci, zvýraznit ji nebo upozornit na něco. Jak se to provádí v AsciiDoc?
NOTE: Nějaká poznámka.
Nebo také zápisem:
[NOTE] Nějaká poznámka.
Kromě klíčového slova NOTE (poznámka) můžete také použít TIP, IMPORTANT (důležité), WARNING (upozornění) a CAUTION (výstraha).
Tím se po provedení obvyklého překladu souboru, např. pomocí asciidoc -a toc text2.txt, vytvoří blok uvozený klíčovým slovem Note. To je sice pěkné, ale aby to bylo ještě hezčí, můžeme tato slova nahradit příslušnými obrázky. Pro použití obrázků místo textu je nutno zadat příkaz asciidoc s dalším přepínačem: -a icons. Kompletní příkaz by tedy vypadal takto:
asciidoc -a toc -a icons text2.txt
Dál musíme k vytvořenému souboru HTML odkazované obrázky ještě přidat. Používané obrázky se nacházejí v adresáři /usr/share/asciidoc/images a právě tento adresář je potřeba zkopírovat k vytvořenému HTML dokumentu. Pokud se právě nacházíte u vytvořeného HTML souboru, provedete zkopírování potřebných obrázků takto:
cp -r /usr/share/asciidoc/images ./
Obrázky
Pro vložení obrázku se používá tato konstrukce:
image:images/tiger.png[Obrázek tygra]
Za klíčovým slovem image: následuje umístění obrázku a volitelně v hranatých závorkách jsou umístěny další parametry obrázku, v našem případě to je jeho popisek.
Kromě toho můžete provádět i běžné operace:
image:images/tiger.png["Obrázek tygra",height=50,link="images/tiger.png"]
Tím se výška obrázku nastaví na 50 px (podobně můžete nastavit šířku - width - obrázku) a zároveň se obrázek bude chovat jako odkaz, který vás po kliknutí přenese na místo určení. Tím je v našem případě ještě jednou tentýž obrázek. Běžně se zde pak volí kombinace náhledu a původního obrázku. Cílem ale může být prakticky cokoliv, internetová adresa i soubor uložený na disku počítače.
Odkazy
Odkazy můžete směřovat na lokální soubory, např. na našeho oblíbeného tygra takto:
link:images/tiger.png[Soubor ke stažení]
Nebo na internetové stránky:
Kdo by neznal http://www.linuxexpres.cz a http://www.abclinuxu.cz[ABC Linuxu]
Je vidět, že odkazy stačí uvést a AsciiDoc je automaticky převede. Pokud chcete jiný text odkazu, pak ho uveďte do hranatých závorek za adresu odkazu.
Na zdrojový soubor s dnešními příklady se můžete opět podívat: text.tgz. Pokud vás zajímá výsledek, pak ho najdete tady: html.tgz. Oba jsou to archivy, které je nutné rozbalit.
Číslování a odrážky
Jednoduchý seznam může vypadat takto:
-- - jídlo * máslo * maso - pití * pivo * víno * ještě jedno víno --
Symboly -- na začátku a na konci seznamu jsou nepovinné, ale slouží k uvození seznamu (určení začátku a konce jednoho seznamu). Mezery na začátku některých řádků jsou nepovinné, ale přispívají k lepší čitelnosti seznamu.
Pokud se podíváte do dokumentace programu, zjistíte, že jsou seznamy (ať už číslované nebo nečíslované) vymezeny trochu jinak, než zde uvádím. Je to z toho důvodu, že mi zanoření se do nižších vrstev seznamu počínaje 3. a další vrstvou nefungovalo. Domnívám se, že to bylo buď starší verzí použitého AsciiDoc, nebo tato funkce ještě není implementována. Jde to obejít, ale docela ztuha.
Pokud bychom chtěli číslovaný seznam, pak to provedeme podobně:
-- . Kočka .. Domácí .. Divoká .. Tlustá . Pes .. Velký .. Malý --
Ještě zmiňme jeden typ seznamu, je to seznam s návěštím, ten s zapisuje takto:
*Včera*:: - bylo pěkně - byl jsem doma *Dnes*:: - prší - jsem v práci
Symboly hvězdiček u slova Včera a Dnes signalizují použití tučného písma, pro návěští jako takové nejsou podstatné.
Vložení zdrojového kódu programu
Ke zvýraznění syntaxe AsciiDoc používá GNU source-highlight, a tak by měl pokrýt snad všechny běžné požadavky na zvýraznění zdrojového kódu. Zdrojový text spolu s odkazem na soubor ke stažení (v našem případě text4.rb) je tento:
.link:text4.rb[text4.rb] [ruby] source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ puts 'Popis cesty je následující:' puts 'doleva ' * 5 + 'doprava ' * 2 source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Zdrojový kód se tedy vkládá mezi značky source a je ohraničen pomocí znaku vlnovka. Řádek [ruby] udává programovací jazyk zdrojového souboru. Pokud byste si navíc přáli vkládat na začátek každého řádku jejich čísla, provedete to takto:
.link:text4.rb[text4.rb] [ruby,numbered] source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ puts 'Popis cesty je následující:' puts 'doleva ' * 5 + 'doprava ' * 2 source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A jak znázornit výstup nějakého programu? V našem případě třeba následovně:
------------------------------------------------------ Popis cesty je následující: doleva doleva doleva doleva doleva doprava doprava ------------------------------------------------------
Vložení jiného souboru
Nejen v situaci, kdy píšete nějaké dlouhé dílo, ale také třeba právě při vkládání zdrojového kódu, se vyplatí vložit místo celého kódu pouze odkaz na soubor, kde se text nachází. Předchozí zápis bychom tedy mohli zkrátit pomocí odkazu na zdrojový soubor takto:
.link:text4.rb[text4.rb] [ruby,numbered] source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ include::text4.rb[] source~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Podobný postup se mi osvědčil i při psaní delších prací, kdy je vhodné umístit každou kapitolu do samostatného souboru a pomocí volání include pak později vložit do hlavního souboru. Díky zakomentování některých kapitol (vstupních souborů) je pomocí tohoto postupu možno zkrátit proces převodu (vytvoření HTML), kdy jednoduše převádíme jen ty části, které zrovna potřebujeme.
A co dál?
Zda AsciiDoc použijete, nebo ne, záleží jenom na vás. Mně program přirostl k srdci právě svojí jednoduchostí a přímočarostí, s jakou se realizují i některé složitější věci (např. vkládání zdrojového kódu programu). AsciiDoc se tak určitě hodí pro psaní kratších i delších prací, učebnic, postupů, dokumentací a dalších. Systém přitom za vás vytvoří to, co je vidět na první pohled - vizuální stránku vašeho díla - a vy se tak budete moci soustředit pouze na to nejdůležitější - na obsah své práce. Pak už stačí jenom psát a psát.