hledat:

Formát XML pro interní dokumentaci TEN-155 CZ

Technická zpráva TEN-155 CZ číslo 1/2000
k dispozici též ve formátech PDF, PostScript a XML.

Pavel Satrapa
1. září 2000

Změny proti předchozí verzi

Praktická zkušenost získaná při přípravě průběžné zprávy za rok 2000 poukázala na některé chybějící konstrukce. Ukázalo se, že je potřeba pro finální zpracování poskytnout prostředky, které by ošetřily některé speciální případy. Sem patří atribut compact u seznamů <ul> a <ol> a atribut continue u prvku <obr>. Byl bych velmi rád, kdybyste tyto atributy chápali jako interní a pokud možno je nepoužívali. Slouží pro finální vyladění vzhledu zprávy.

Druhá skupina změn je zaměřena na doplnění některých chybějících konstrukcí. Jedná se především o prvek <uv> realizující české uvozovky a odlišení spojovníku (-) od pomlčky (-). Kromě nich jsem přidal prvek <footnote> pro poznámky pod čarou (používejte prosím střídmě).

Jelikož některé zprávy budou vznikat v angličtině, přidal jsem prvku <zprava> atribut jazyk, kterým lze určit výstupní jazyk.

Úvod - základní východiska

Cílem bylo vytvořit sadu standardů, doporučení a nástrojů, které by sjednotily a zjednodušily vytváření interních dokumentů sítě TEN-155 CZ jak v digitální, tak v tištěné podobě. Abychom zjistili, jaké jsou preference a požadavky řešitelů uspořádali jsme jednoduchou anketu, dotazující se na preferované a akceptovatelné prostředky pro práci s texty.

Výsledky jednoznačně ukázaly, že drtivá většina řešitelů běžně edituje HTML dokumenty ve zdrojovém tvaru a tudíž jí nečiní potíže připravovat dokumenty, které se svým tvarem budou podobat HTML. Volba celkem jednoznačně padla na jazyk XML, který je na jedné straně dostatečně obecný a umožňuje přizpůsobení potřebám, na straně druhé je dostatečně jednoduchý.

Vytvořili jsme definici typu dat (DTD) popisující strukturu dokumentu, dostupné prvky XML a pravidla pro jejich používání. Základním východiskem pro tuto definici bylo, aby se co nejvíce podobala jazyku HTML a tudíž, aby se řešitelé pohybovali v prostředí pro ně povědomém. Změny proti HTML byly motivovány následujícími požadavky:

• zjednodušení 1 - HTML obsahuje zbytečně mnoho konstrukcí, které budou uživatele svádět ke kreativitě a z ní plynoucím vzhledovým nekompatibilitám
• zjednodušení 2 - některé konstrukce (např. vložené obrázky s popisem) lze v HTML realizovat jen velmi komplikovaně, navržený jazyk by je měl nabídnout podstatně systémovějším a jednodušším způsobem
• sladění tabulkového modelu HTML a LaTeXu - aby se daly rozumným způsobem generovat obě výstupní verze dokumentu (HTML a papírová v LaTeXu), bylo potřeba navrhnout takový model tabulek, za kterého by šly rozumným způsobem generovat tabulky pro oba systémy

Základní kostra zprávy

Základ zprávy tvoří určitá pevně daná povinná sekvence prvků. Je to

<?xml version="1.0" encoding="ISO-8859-2"?>
<!DOCTYPE zprava SYSTEM "techrep.dtd">

<zprava cislo="pořadové číslo">
<nazev>Název zprávy</nazev>
<autor>Autor/autoři zprávy</autor>
<datum>Datum vydání</datum>

... vlastní text zprávy ...

</zprava>

První dva řádky identifikují dokument jako XML a definují jeho typ (DTD). Berte je prosím jako dogma. Význam zbytku je myslím jasný.

Celá zpráva musí být obalena prvkem <zprava>. Tento prvek má definovány dva atributy: povinný cislo, jehož obsahem je identifikační číslo zprávy, a nepovinný jazyk. Atribut jazyk definuje jazykovou verzi zprávy - má vliv na generované nadpisy a tvar uvozovek. Je podporována jen česká a anglická verze. Má-li hodnotu en, je zpráva považována za anglickou, ve všech ostatních případech (i pokud jazyk chybí) se zpráva bere za českou.

Důležité je, že vlastní text zprávy smí tvořit jen sekvence prvků <hX> pro nadpisy jednotlivých částí a prvků <p>, které obsahují odstavce textu. Všechny ostatní prvky musí být zabaleny (zpravidla do <p>).

Základní formátování textu

Text je obvyklým způsobem rozdělen do odstavců. Každý odstavec je vymezen prvkem <p> a smí obsahovat prakticky všechny ostatní prvky DTD.

Jazyk XML zavádí speciální význam pro některé znaky - například "<" a ">" slouží k vymezení jednotlivých prvků. Chcete-li do textu vložit některý z těchto znaků, musíte jej zapsat ve formě speciální konstrukce. Odpovídající konstrukce najdete v posledním sloupci tabulky. Kromě nich máte k dispozici ještě několik dalších entit, které usnadňují správné vkládání některých často používaných textů a speciálních znaků. Jejich souhrn uvádí tabulka. Názvy většinou pocházejí z HTML.

Pro vyznačování (zvýrazňování) určitých částí či prvků textu slouží dva druhy XML prvků. Jedny představují vyznačení fyzické, kdy přímo určujete, jakým druhem písma má být dotyčná pasáž vysázena. Druhá skupina zajišťuje vyznačení symbolické, kdy text zařadíte do určité kategorie. Podle toho pak bude stanoveno jeho standardní vyznačení. Pokud je pro váš účel k dispozici symbolická skupina, vždy jí dávejte přednost. Jedině tak lze zajistit, že vyznačování určité kategorie textů (např. názvy souborů) bude ve všech dokumentech konzistentní.

Pro formátování bloků písma máte k dispozici prvek <blockquote>, jehož obsah bude zobrazen na užších řádcích s rozšířenými okraji vlevo i vpravo.

Dalším blokovým prvkem je <pre>, který slouží ke vkládání "předformátovaného" textu. Jeho obsah se zobrazuje neproporcionálním písmem, dodržují se mezery a konce řádků. Používá se pro ukázky konfiguračních souborů a podobně.

Posledním prvkem, o kterém se zde zmíním, je prázdný prvek <br/>, kterým si vynutíte konec řádku. Jelikož nemá žádný obsah, musí se psát buď jako nepárový s lomítkem před ukončujícím znakem ">" (takto je zapsán na začátku odstavce) nebo ve formě <br></br>. Je to hloupé, ale takhle to vyžaduje XML...

Části textu

Často je třeba rozdělit text na určité části, někdy i víceúrovňově. K tomuto účelu slouží prvky <h1>, <h2> a <h3>, do nichž uzavírejte nadpisy jednotlivých částí - například

<h1>Návrh řešení</h1>
<p>Tady bude zahajující text části.</p>

<h2>Varianta 1</h2>
<p>Text první varianty.</p>

<h2>Varianta 2</h2>
<p>Text druhé varianty.</p>

S rostoucím číslem klesá význam a míra zvýraznění nadpisu. Hlavní části textu by proto měly mít nadpisy uzavřené do <h1>. Pokud je některá z nich rozdělena na podčásti, ty by měly mít nadpisy <h2> a případné části těchto částí pak <h3>. Hlubší úroveň členění se nepředpokládá.

Nepřeskakujte! Členíte-li část s nadpisem <h1>, použijte pro nadpisy jejích oddílů <h2>, nikoli <h3>.

Seznamy

Prvky pro seznamy jsou plně kompatibilní HTML (až na to, že nemají žádné atributy). Jediným nezvykem by mohlo být, že zde musíte všechny prvky uzavírat.

Seznam s odrážkami je uzavřen do prvku <ul> (unordered list). Každá jeho položka je uzavřena do <li>. Například zdrojový text

<ul>
<li>první položka</li>
<li>druhá</li>
<li>a třetí</li>
</ul>

vytvoří

• první položka
• druhá
• a třetí

Číslovaný seznam se používá úplně stejně. Jediným rozdílem je, že obalovým prvkem je <ol> (ordered list) místo <ul>.

Pro zmiňované dva druhy seznamů máte k dispozici atribut compact, který zajistí, že jejich vzhled bude kompaktnější (vynechává se méně místa). Je určen pro závěrečné formátování papírové verze dokumentů a raději jej nepoužívejte. Zapisuje se ve tvaru <ul compact="1">...</ul>.

Seznam s nadpisy má složitější konstrukci. Celý je zabalen do prvku <dl> (definition list). Každá položka má dva prvky. <dt> (definition term) zavádí její nadpis (jméno). Za ní pak následuje <dd> (definition description) s popisem či textem položky. Například zdrojový text

<dl>
<dt>raz</dt>
<dd>Tady je vysvětlující text k první položce seznamu.
V některých případech může být i dosti dlouhý, lze do
něj zařadit i řadu dalších prvků.</dd>

<dt>dva</dt>
<dd>Tady je vysvětlující text ke druhé položce seznamu.</dd>
</dl>

vytvoří takovýto seznam:

raz

Tady je vysvětlující text k první položce seznamu. V některých případech může být i dosti dlouhý, lze do něj zařadit i řadu dalších prvků.

dva

Tady je vysvětlující text ke druhé položce seznamu.

Obrázky

U obrázků jsem se opravdu hodně snažil o maximální zjednodušení. DTD podporuje vlastně jen jediný typ: vložený obrázek s popisem, protože to je podle mého názoru jediná odrůda obrázků, které se v odborných textech vyskytují. Vkládají se konstrukcí

<obr src="název souboru">Popis (titulek) obrázku</obr>

Název souboru se zadává bez přípony. Konverzní program automaticky předpokládá, že pro on-line verzi je obrázek ve formátu GIF a ke jménu připojí příponu .gif, zatímco pro textovou verzi se předpokládá formát Encapsulated PostScript a přidává se přípona .eps. Například ukázkový obrázek byl vytvořen prvkem

<obr src="cfgschem">Ukázkový obrázek</obr>

Obrázek je potřeba připravit v odpovídajících formátech. Vzhledem ke koncepci výstupních stránek je třeba, aby GIF verze nepřesáhla šířku 450 obrazovkových bodů a EPS verze šířku 12 cm a výšku 20 cm.

Tabulky

Zápis tabulek silně vychází z HTML a většina značek je společných. Z LaTeXu jsem však použil specifikaci zarovnání sloupců při zahájení tabulky. Jednak proto, že ji stejně potřebuji, jednak proto, že je docela praktická.

Celá tabulka je obalena prvkem <tab>, jehož zahajovací značka musí být opatřena povinným atributem sloupce, který určuje způsob zarovnání jednotlivých sloupců. Jeho hodnotou je řetězec znaků, kdy každému sloupci odpovídá jeden znak. Jejich významy najdete v tabulce.

Obsahem tabulky je libovolně dlouhá posloupnost řádků zabalených do prvku <tr> (table row). Každý řádek je pak složen z buněk tabulky, které mohou být buď obyčejné (prvek <td> - table data) nebo mohou představovat záhlaví sloupce či řádku (prvek <th> - table head). Celkový počet buněk v řádku by měl odpovídat počtu sloupců podle atributu sloupce.

Prvky <td> a <th> mají definováno několik atributů. colspan="číslo" umožňuje roztáhnout buňku přes několik sloupců. Analogicky rowspan="číslo" roztáhne buňku do několika řádků (v řádcích, do kterých je roztažena, je třeba ji vynechat). Vzhledem k tomu, že LaTeX nepodporuje několikařádkové buňky, raději se tomuto atributu vyhýbejte (mělo by to fungovat, ale výsledek není nijak zvlášť pohledný).

Atribut align="hodnota" umožňuje předepsat vodorovné zarovnání. Má přednost před implicitním zarovnáním sloupce. Přípustnými hodnotami jsou left, right a center. Atribut valign="hodnota" určuje svislé zarovnání. Opět doporučuji nepoužívat, protože LaTeX je nepodporuje. Přípustné hodnoty: top, middle a bottom.

Prvkům <tr>, <td> a <th> lze přiřadit také atribut bgcolor="#RRGGBB", který určuje barvu jejich podkladu. Ta se zadává způsobem obvyklým z WWW - pomocí šesti hexadecimálních číslic, určujících intenzitu červené, zelené a modré složky. Používejte velmi vzácně nebo raději vůbec ne. V papírové verzi bude pravděpodobně ignorováno.

Za řádky je v tabulce povinně obsažen prvek <nazev>, jehož obsahem je popis (titulek) tabulky.

Jako příklad lze uvést poslední tabulku s významem jednotlivých písmen pro zarovnání sloupců. Vznikla z tohoto zdrojového kódu:

<tab sloupce="cl">
<tr><td><tt>l</tt></td>
    <td>sloupec zarovnaný doleva</td></tr>
<tr><td><tt>c</tt></td>
    <td>centrovaný sloupec</td></tr>
<tr><td><tt>r</tt></td>
    <td>sloupec zarovnaný doprava</td></tr>
<nazev>Význam písmen v atributu <tt>sloupce</tt></nazev>
</tab>

Tabulky nelze vnořovat! Nepoužívejte tabulky pro formátování textu, jak bývá zvykem z HTML. Jsou určeny skutečně pouze pro informace tabulkovitého charakteru - krátké texty rozložené do řádků a sloupců. Chcete-li například vytvořit tabulku pojmů s vysvětlujícími texty, je vhodnější použít seznam s nadpisy (prvek <dl>).

Odkazy

Syntaxi pro odkazy jsem převzal z HTML. Zapisuje se ve tvaru

<a href="cílová adresa">odkazující text</a>

Například zdrojový text

<a href="http://www.ten.cz/">WWW server TEN-155 CZ</a>

vede k tomuto výsledku:

WWW server TEN-155 CZ

Chcete-li se odkázat na některou část svého textu, musíte jí nejprve přidělit identifikátor. To zajistí atribut id, který můžete přidělit prvkům <h1>, <h2>, <h3>, <obr>, <tab> a <p>. Přidělování identifikátoru odstavci (prvku <p>) považuji za velmi problematické a doporučuji se mu vyhnout.

Odkaz na takto zavedený identifikátor obstará standardní prvek <a>, jehož atribut href bude mít hodnotu #identifikátor. Příklad obrázku s identifikátorem a textu, který se na něj odkazuje:

<obr src="ten-topo" id="topologie">Topologie sítě</obr>

Topologii sítě vidíte na <a href="#topologie">obrázku</a>.

Opět se to silně podobá HTML.

Citace literatury

Aparát pro citaci použité literatury má dva základní prvky: informace o knize v seznamu literatury a odkaz na ni v textu. Informace o citovaných zdrojích bývá zvykem shromáždit v závěru práce. Musí být obaleny prvkem <seznamknih>. Odkazy na jednotlivé knihy (citace) mohou být pochopitelně libovolně roztroušeny v celém textu.

Každá citovaná publikace musí být uzavřena do prvku <kniha> s povinným atributem id, který musí obsahovat jednoznačný identifikátor knihy. Doporučuji používat identifikátory složené z počátečních tří písmen příjmení autora (resp. prvního z autorů) a posledních dvou číslic letopočtu vydání - např. pro tuto zprávu bych použil Sat99. Pokud takto sestrojený identifikátor není jednoznačný, bývá zvykem přidat za letopočet ještě malé písmeno, které zajistí jednoznačnost, např. Sat99a.

Jednoduchý seznam literatury obsahující jedinou publikaci může vypadat takto:

<seznamknih>
<kniha id="Wal97">
Wall L., Christiansen T., Schwartz R. L.:
<i>Programování v jazyce Perl</i><br/>
Computer Press, 1997, ISBN 80-85896-95-8
</kniha>
<seznamknih>

Jeho výslednou podobu najdete v seznamu literatury na konci zprávy. Pokud by měl obsahovat více publikací, prvek <kniha> by se vyskytl několikrát.

Chcete-li se na některou knihu odkázat v textu, použijte prvek <cite>. Je prázdný a identifikátor citované publikace musíte uvést jako hodnotu jeho atributu href. Například na výše uvedenou knihu se lze odkázat pomocí

<cite href="Wal97"/>

Do textu se vloží v této podobě: [Wal97].

Použitá literatura

[Wal97]

Wall L., Christiansen T., Schwartz R. L.: Programování v jazyce Perl Computer Press, 1997, ISBN 80-85896-95-8

Poznámky pod čarou

Prostřednictvím prvku <footnote> lze do textu lze vkládat poznámky pod čarou. V místě svého výskytu vygeneruje symbol (pořadové číslo) poznámky. Text poznámky, který je dán tělem prvku <footnote>, se odsune na konec stránky¹ (ať už se jedná o stránku papírovou či HTML stránku).

Zdrojový text, který vygeneroval poznámku v předchozím odstavci, vypadá takto:

stránky<footnote>asi takto</footnote> (ať už

DTD

Definice typu dat pro technické zprávy TEN-155 CZ vypadá následovně:

<!- zakladni struktura dokumentu:
        <zprava cislo="cislo zpravy">
        <nazev>Jmeno zpravy</nazev>
        <autor>Jmeno(a) autora(u)</autor>
        <datum>datum vydani</datum>
        
        <h1>nadpis prvni casti</h1>
        <p>tady text...</p>
        atd.
        
        </zprava>
->

<!- pomocne definice ->
<!ENTITY % napis
        "(#PCDATA|b|i|tt|sup|sub|soubor|prikaz|vstup|
            adresa|uv|cite|footnote|br)*"
>
<!ENTITY % cokoli
        "(#PCDATA|b|i|tt|sup|sub|soubor|prikaz|vstup|
            adresa|uv|cite|footnote|ul|ol|dl|blockquote|
            br|a|p|obr|tab|pre)*"
>
<!ENTITY % zarovnani
        "align (left|right|center) #IMPLIED
         valign (top|bottom|middle) #IMPLIED"
>
<!ENTITY % id
        "id CDATA #IMPLIED"
>

<!- entity napisoveho charakteru ->
<!ENTITY ten "TEN-155~CZ">
<!ENTITY cesnet "CESNET,~z.~s.~p.~o.">

<!- specialni znaky ->
<!ENTITY sect "§">
<!ENTITY ldots "...">
<!ENTITY times "×">
<!ENTITY deg "°">
<!ENTITY copy "Š">
<!ENTITY reg "Ž">
<!ENTITY vlnka "~">

<!- znacky nejvyssi urovne ->
<!ELEMENT zprava (nazev,autor,datum,(p|h1|h2|h3)*)>
<!ATTLIST zprava cislo CDATA #REQUIRED
                 jazyk CDATA #IMPLIED>
<!ELEMENT nazev %napis;>
<!ELEMENT autor %napis;>
<!ELEMENT datum %napis;>

<!- jedine znacky povolene primo v tele zpravy ->
<!ELEMENT h1 %napis;>
<!ATTLIST h1 %id;>
<!ELEMENT h2 %napis;>
<!ATTLIST h2 %id;>
<!ELEMENT h3 %napis;>
<!ATTLIST h3 %id;>
<!ELEMENT p %cokoli;>
<!ATTLIST p %id;>

<!- seznamy (musi byt zabaleny do <p>) ->
<!ELEMENT ul (li)*>
<!ATTLIST ul compact CDATA #IMPLIED>
<!ELEMENT ol (li)*>
<!ATTLIST ol compact CDATA #IMPLIED>
<!ELEMENT dl (dt*,dd)*>
<!ELEMENT li %cokoli;>
<!ELEMENT dt %napis;>
<!ELEMENT dd %cokoli;>

<!- odsazeni (take jen uvnitr <p>) ->
<!ELEMENT blockquote %cokoli;>

<!- ukončení řádku ->
<!ELEMENT br EMPTY>

<!- vkladani obrazku
     pouziti:  <obr src="nazev_souboru">Slovni popis obrazku</obr>
                  nazev souboru se uvadi bez pripony
     priklad:  <obr src="schema">Organizacni schema</obr>
->
<!ELEMENT obr %napis;>
<!ATTLIST obr src CDATA #REQUIRED
              continue CDATA #IMPLIED
              %id;>

<!- tabulky
     jsou organizovany podobne jako v HTML, navic je vsak treba v uvodu
     definovat zarovnani sloupcu; kazdy sloupec je reprezentovan jednim
     pismenem:  l .. zarovnat doleva
                c .. centrovat
                r .. zarovnat doprava
     napr. <tab sloupce="lrr">..</tab> je tabulka o 3 sloupcich; prvni
     je zarovnan nalevo, dalsi dva napravo
     kompletni priklad:
     
     <tab sloupce="lrrr">
     <tr><th></th><th colspan="3">Trzba</th></tr>
     <tr>
      <th>Prodejna</th>
      <th>Leden</th>
      <th>Unor</th>
      <th>Celkem</th>
     </tr>
     <tr>
      <td>Lesni</td>
      <td>158 219</td>
      <td>131 227</td>
      <td><b>289 446</b></td>
     </tr>
     <nazev>Celkový objem prodeje</nazev>
     </tab>
->
<!ELEMENT tab (tr*,nazev)>
<!ATTLIST tab sloupce CDATA #REQUIRED
              %id;>
<!ELEMENT tr (td|th)*>
<!ATTLIST tr bgcolor CDATA   #IMPLIED>
<!ELEMENT td %cokoli;>
<!ATTLIST td colspan CDATA   "1"
                rowspan CDATA   "1"
                %zarovnani;
                bgcolor CDATA   #IMPLIED>
<!ELEMENT th %cokoli;>
<!ATTLIST th colspan CDATA   "1"
                rowspan CDATA   "1"
                %zarovnani;
                bgcolor CDATA   #IMPLIED>

<!- citovaná kniha a odkaz na ni ->
<!ELEMENT seznamknih (kniha)*>
<!ELEMENT kniha %napis;>
<!ATTLIST kniha id CDATA #REQUIRED>
<!ELEMENT cite EMPTY>
<!ATTLIST cite href CDATA #REQUIRED>

<!- odkazy ->
<!ELEMENT a %cokoli;>
<!ATTLIST a  href CDATA #IMPLIED>

<!- predformatovany text ->
<!ELEMENT pre (#PCDATA)>

<!- pismo ->
<!ELEMENT b %napis;>
<!ELEMENT i %napis;>
<!ELEMENT tt %napis;>
<!ELEMENT sup %napis;>
<!ELEMENT sub %napis;>

<!ELEMENT soubor %napis;>
<!ELEMENT prikaz %napis;>
<!ELEMENT vstup  %napis;>
<!ELEMENT adresa %napis;>

<!- uvozovky ->
<!ELEMENT uv %napis;>

<!- poznámka pod čarou ->
<!ELEMENT footnote %napis;>

 

Poznámky:

2. asi takto