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