Co to je sgml

Tento článek popisuje versi 1.0.3 balíku sgml-tools. Starší verse dodávané např. s distribucí Linuxu Red Hat 5.0 nemají preprocesor a mohou se odlišovat i v jiných vlastnostech od tohoto textu.

Základní struktura dokumentu

<!doctype linuxdoc system>

<article>

<title>Co z toho asi bude
<author>Bílá Paní

<date>31. prosince 1999

<abstract>
Informace o generálním sjezdu všech strašidel
   k problematice roku 2000.
</abstract>

<toc>

</article>

Formátování textu určují příkazy, uvedené v úhlových závorkách < >. Většina příkazů se vztahuje jen na blok textu, potom je ohraničena znaky <příkaz> a </příkaz>.

Každý SGML dokument musí začínat řádkem <!doctype linuxdoc system>. Ten specifikuje DTD typ SGML dokumentu. Příkaz <article> ... </article> říká, že použijeme styl "article". Význam značek <title>, <author> a <date> je zřejmý, <abstract> ... </abstract> může obsahovat stručný popis dokumentu. Příkaz <toc> vysází ve výsledném textu obsah.

Nadpisy kapitol, odstavce

<sect>Kapitola

<sect1>Podkapitola

<p>
Text odstavce.

Za zmínku stojí především uvedení značky <p>. Mezi nadpisem kapitoly a textem být musí, jinak by konvertor nepoznal, kde končí nadpis a začíná odstavec. Při oddělování odstavců mezi sebou je možné použít buď <p>, nebo stačí jen vynechat prázdný řádek.

Zvýrazňování textu

U podobných příkazů je povolena ještě syntax tohoto tvaru: <em/ ... /. Pochopitelně, že text uvnitř příkazu nesmí obsahovat lomítka. To připouští pouze první syntax.

Prostředí verbatim pro sazbu textu beze změny tak, jak je ve zdrojovém textu, lze vytvořit značkami

<verb>
Nějaký text. @#$%^&.
</verb>

Uvnitř verbatim prostředí musí být použit příkaz &ero; pro znak & a &etago; místo dvojice znaků </. Uvnitř verbatim prostředí se nesmí vyskytovat ani sekvence \end{verbatim}, protože koliduje s LaTeXovým koncem verbatim prostředí.

Obdobný příkazu verbatim je <code> main() {} </code>. Ten se užívá k sazbě zdrojového kódu. Jediný rozdíl oproti verb je, že před a za textem v příkazu se umístí vodorovná čára přes celou šířku sazby.

Prostředí tscreen nastaví font na tt a odsadí sázený text. Ten je opět zadán ve tvaru

<tscreen>
Nějaký text.
</tscreen>

Obdobné prostředí quote provede totéž, ale nenastaví font na tt. Užívá se pro sazbu citátů.

Výčty

• itemize jsou položky označené puntíkem,
• enum jsou automaticky číslované a
• descrip je popisný výčet.

První dva typy výčtů mají tuto strukturu:

<itemize>
  <item>První položka,
  <item>Druhá položka.
</itemize>

Jak výčet dopadne je vidět na začátku odstavce. Poslední, popisný výčet, se vytváří trochu jinak:

<descrip>
  <tag>Položka</tag> A její vysvětlení.
  <tag>Jiná</tag> Položka jiná.
</descrip>

Sazba speciálních znaků

• & - &amp;
• < - &lt;
• > - &gt;
• $ - &dollar;
• # - &num;
• % - &percnt;
• ~ - &tilde;
• " - &dquot;
• | - &verbar;
• - &times;
• @ - &commat;

Takových znaků je podstatně více, doporučuji podívat se do dokumentace, dodávané s balíkem sgml-tools.

Odkazy a reference

<sect>O bezhlavém rytíři<label id="hlava">

V textu je potom možné se odkazovat na tuto kapitolu příkazem <ref id="hlava" name="O bezhlavém rytíři">. Argument name se využije při tvorbě HTML verse dokumentu, kde nebude uvedeno číslo, ale přímo název kapitoly s hypertextovým odkazem na ni. V názvech odkazů, tedy v argumentu id, by se neměly vyskytovat žádné speciální znaky, ani podtržítko _, ani české znaky.

Odkazy do prostoru Internetu mají formát:

<url url="http://www.strasidla.org/~jozin/"
   name="Jóžin z bážin">

Argument name se použije v HTML versi jako odkaz a v TeXové versi pro popis odkazu.

Pro odkazy na emailové adresy je lepší použít alternativu

<htmlurl url="mailto:hejkal@huste-lesy.edu"
name="mailto:hejkal@huste-lesy.edu">

Tak se při výstupu do textu neobjeví adresa dvakrát za sebou, jednou jako URL a podruhé jako popis, ale přesto zůstane správný odkaz v HTML versi.

Podmínky "preprocesoru"

Tento <#if output="latex">TeXový</#if> dokument...

Slovo TeXový se objeví jen v LaTeXové versi dokumentu. V příkazu je povolen i znak "nebo": name="latex|html" vysází takový podmíněný text v LaTeXové i HTML versi.

Jako argument příkazu #if je možné použít i libovolnou konstantu, třeba version="oficialni". Pokud potom version bude nastaveno na oficialni nebo nebude nastaveno, výstup bude text v podmínce obsahovat. Konstanta se nastaví na příkazové řádce při překladu dokumentu (při výstupu do HTML) takto:

 sgml2html -D version=moje text.sgml

Obdobně existuje příkaz <#unless>, který se chová opačně než #if. Tedy vloží podmíněný text jen tehdy, neplatí-li podmínka uvedená v argumentu.

Na tyto příkazy Linuxdoc-sgml je třeba dát si obzvláště pozor. Protože jsou zpracovány preprocesorem, může se při chybném použití stát, že samotný překladač SGML bude vydávat zcela nesrozumitelné chybové hlášky na úplně jiných místech textu.

Poznámky k české sazbě

Také uvozovky se v češtině zapisují jinak než v jiných jazycích. Doporučuji i v SGML používat pro počáteční uvozovky dva znaky čárka hned za sebou (,,) a pro koncové dva znaky zpětný apostrof za sebou (``). TeX v takovém případě vysází správné české uvozovky a i v ostatních formátech to vypadá lépe než znak palec (").

Překlad Linuxdoc-sgml

• sgmlcheck strasidla.sgml - Provede syntaktickou kontrolu dokumentu.

• sgml2txt -c latin strasidla.sgml - Vygeneruje textovou versi dokumentu. Je potřeba říci, že dokument je v latin 1, jinak poničí české znaky.

• sgml2html strasidla.sgml - Vygeneruje stránky HTML jazyka.

• sgml2latex -p a4 -o tex strasidla.sgml - Vygeneruje LaTeXový zdrojový kód. S touto versí je pro češtinu nejvíce práce. Protože sgml-tools češtinu neznají, musí se vygenerovat tímto příkazem zdrojový kód pro cslatex a na jeho začátku nahradit řádku \usepackage[latin1]{inputenc} za řádek \usepackage{czech}. Tím načteme styly cslatexu a budeme mít správně dokonce i dělení slov. Pak se nejméně dvojím překladem cslatex strasidla vygeneruje DVI a případně dvips strasidla i Postscript.

Další konvertory jsou sgml2info, sgml2lyx a sgml2rtf.

Kde lze sgml-tools získat a závěrečné postřehy

Linuxdoc-sgml je užitečný balík pro psaní dokumentace, u které je požadován výstup do co největšího počtu formátů spíše, než vytříbená typografická kvalita. Tištěné verse dokumentů mají daleko ke kráse textů psaných přímo v TeXu. Přesto je na příkladu celého Linux Documentation Projectu vidět, že jej lze použít i na velkých projektech s dobrými výsledky. Jako ostatně vždy, musí český uživatel počítat s tím, že narazí na drobné problémy v důsledku používání svého rodného jazyka.