- předchozí článek - následující článek - obsah - úvodní stránka -

Linuxové noviny 08-09/98

Jak na Linuxdoc-sgml

Michal Choura, 2. srpna 1998

Co to je sgml

Balík programů sgml-tools byl vytvořen Mattem Welshem jako jednotné prostředí pro psaní dokumentů projektu LDP (Linux Documentation Project). Utility jsou nadstavbou nad SGML a autoři mohou psát své texty v jednoduchém a přehledném formátu, jakým SGML je. Dokument je potom možné zformátovat do podoby čistého textu, systému info, HTML stránky s hypertextovými odkazy, LaTeXu či Postscriptu k vytištění, a dokonce i do formátů editoru LyX nebo do rtf. Struktura SGML dovoluje jednoduše napsat další konvertory do jiných, třeba i dnes neznámých formátů.

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

Každý dokument v Linuxdoc-sgml má takovouto základní kostru:

<!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

Pro nadpisy kapitol se používají příkazy <sect>, <sect1>, <sect2>, <sect3> a <sect4>. Syntaxe v dokumentu je následující:

<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

Základní způsob zvýraznění textu je kursiva. Tu vysadíme příkazy <em> ...kursiva... </em>. Sazbu tučného textu je možno dosáhnout příkazy <bf> ...tučně.. </bf>. Neproporcionální font psacího stroje lze vytvořit příkazy <tt> ...strojově... </tt>.

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

Linuxdoc-sgml umí sázet tři druhy výčtů:

  • 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ů

V SGML je mnoho tzv. speciálních znaků, které je třeba sázet sekvencemi tvaru &něco;. Mezi nejdůležitější patří:

  • & - &amp;
  • < - &lt;
  • > - &gt;
  • $ - &dollar;
  • # - &num;
  • % - &percnt;
  • ~ - &tilde;
  • " - &dquot;
  • | - &verbar;
  • x - &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

Pokud se chcete odkazovat na nějakou kapitolu, je třeba přidat za nadpis kapitoly takovouto definici:

<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"

Novější verse sgml-tools obsahují velmi jednoduchý preprocesor. S jeho použitím je možné vytvářet odlišný text pro různé výstupní formáty. Základní struktura je:

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ě

V češtině je pravidly pravopisu stanoveno, že by neměly na koncích řádků zůstávat jednoslabičné předložky. V SGML je na takovou možnost pamatováno a je definována, stejně jako v TeXu, pevná mezera, ve které nikdy nebude proveden řádkový zlom. Tato mezera se zapisuje jako vlnovka ~ a měla by být ve všech ke zlomu nevhodných místech uváděna.

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

Balík sgml-tools obsahuje sadu skriptů, které poslouží k pohodlnému překladu dokumentů. Nejdůležitější z nich jsou:

  • 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

Balík sgml-tools má svou domovskou stránku http://www.sgml-tools.org/, na které lze získat nejnovější versi a i další podrobnější dokumentaci.

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


- předchozí článek - následující článek - obsah - úvodní stránka -