DocSys: systm pro generovn dokumentace

Transkript

Systém pro generování dokumentace
DocSys
Uživatelská příručka
Výklad jazyka pro tvorbu dokumentace
1. Úvod ......................................................................................................................................1
2. Principy dokumentování........................................................................................................3
2.1 Úvod do dokumentování .................................................................................................3
2.2 Struktura dokumentace ....................................................................................................4
2.3 Dokumentační komentáře................................................................................................5
3. Struktura dokumentačního bloku...........................................................................................7
3.1 Metasekce ........................................................................................................................8
3.2 Sekce................................................................................................................................9
3.3 Jednoduché bloky ..........................................................................................................10
4. Zápis obsahu sekce ..............................................................................................................11
4.1 Makra.............................................................................................................................12
4.2 Layout............................................................................................................................12
4.3 Zpracování řídících znaků .............................................................................................13
5. Standardní tagy ....................................................................................................................15
5.1 Speciální tagy ................................................................................................................16
5.1.1 Paragrafy a tag para ................................................................................................16
5.1.2 Tagy link a obj........................................................................................................18
5.1.3 Tag code .................................................................................................................19
5.2 Běžné tagy .....................................................................................................................20
5.2.1 Jednoduché seznamy ..............................................................................................21
5.2.2 Pokročilejší seznamy ..............................................................................................21
5.2.3 Tabulky s pevným počtem sloupců ........................................................................22
5.2.4 Tabulka s proměnným počtem sloupců..................................................................24
5.2.5 Jednoduché formátovací tagy .................................................................................24
5.2.6 Vkládání externích odkazů .....................................................................................25
5.2.7 Ostatní běžné tagy ..................................................................................................25
5.3 Méně běžné standardní tagy ..........................................................................................26
5.3.1 Obecná tabulka .......................................................................................................26
5.3.2 Seznamy .................................................................................................................27
5.4 Přehled tagů ...................................................................................................................28
6. Standardní makra.................................................................................................................30
7. Standardní a automaticky generované sekce .......................................................................32
8. Titulní stránka......................................................................................................................36
9. Vygenerované XML dokumenty .........................................................................................38
9.1 Organizace souborů .......................................................................................................39
9.2 Kostra dokumentů..........................................................................................................41
9.3 Indexy ............................................................................................................................43
9.4 Dokumentace entit.........................................................................................................46
9.5 Titulní stránka................................................................................................................48
10. Jazykový kontext DocSys..................................................................................................50
Dodatky ...................................................................................................................................54
A. Gramatika jazyka DocSys...............................................................................................54
B. Schémata XML dokumentů ............................................................................................56
1. Úvod
DocSys je systém pro generování dokumentace k softwarovým projektům z formátovaných
komentářů ve zdrojových textech. Je vhodný zejména pro vytváření dokumentace k programovým
rozhraním a knihovnám.
Výstupem systému DocSys je dokumentace v podobě strukturovaných XML dokumentů
propojených navzájem odkazy a nesoucích množství sémantické informace. XML je progresivní
formát pro předávání dat mezi aplikacemi, zvlášť vhodný pro předávání strukturovaných textových
dat, kterými je právě výstup systému DocSys. V současnosti existuje řada aplikací, které umějí
XML zpracovávat a transformovat nejrůznějším způsobem pro dosažení rozličných výsledků.
Systém DocSys sám o sobě neusiluje o kompletní zpracování dokumentace, protože možností, jak
výsledek může vypadat a v jakém formátu má být, je příliš mnoho. Místo toho nabízí výstup ve
formátu, který je snadno dále zpracovatelný již existujícími nástroji mnoha různými způsoby.
Nejsnazší a nejpřirozenější možností je transformace XML do HTML, pro což je ve standardní
instalaci DocSys přibalena podpora; HTML je ideální volbou, jak výslednou dokumentaci
zpřístupnit v čitelném tvaru jejím uživatelům při zachování jejího přirozeného hypertextového
charakteru.
Tato část dokumentace je součástí uživatelské příručky systému DocSys a věnuje se syntaxi
zdrojového textu dokumentace a jeho transformaci do XML dokumentů. Zdrojový text
dokumentace se zapisuje pomocí jazyka podobného jazyku XML a pro jeho zápis lze použít
libovolný textový editor. Tato část uživatelské příručky se proto vůbec nezabývá uživatelským
rozhraním, které systém DocSys nabízí a které nabízí funkce, jež se snaží vytváření dokumentace
uživateli usnadnit.
1
2
2. Principy
dokumentování
Obsahem této kapitoly je seznámení se strukturováním dokumentace a se způsobem jejího
začlenění do zdrojových textů projektů, které mají být dokumentovány. Budou vysvětleny důležité
pojmy, které se budou užívat i v ostatních částech dokumentace systému DocSys.
Pro vyložení syntaxe budou používány běžné metaznaky: [ ] uzavírají nepovinnou část
syntaxe, | značí alternativní možnosti, ( ) uzavírají metakomentář, ... značí opakování předchozího
atd.
2.1 Úvod do dokumentování
Již v úvodní kapitole bylo zmíněno, že se dokumentace zapisuje jazykem podobným jazyku
XML. Dokumentace se zapisuje v podobě komentářů přímo do zdrojových souborů programu,
knihovny či jiného softwarového díla, které má být dokumentováno. Tento přístup v současnosti
používají snad všechny systémy na generování dokumentace, neboť má řadu výhod. Zřejmě
největší výhodou je, že zdrojový text dokumentace slouží jako komentář přímo ve zdrojovém textu
programu a tvoří jeho nedílnou součást – to usnadňuje jak jeho aktualizace, tak i přenos.
3
Aby programátor mohl psát své vlastní komentáře, které nemají mít s dokumentací nic
společného, musí být komentáře se zdrojovým textem dokumentace (tzv. dokumentační komentáře)
od ostatních běžných komentářů odlišeny. Např. v jazyce C++ komentář začíná řetězcem /* a za
dokumentační komentáře považuje systém DocSys komentáře uvozené řetězcem /**. Obsahem
následujících dvou oddílů této kapitoly je, jak tyto dokumentační komentáře vypadají navenek i
uvnitř a jaký je jejich vztah k vlastnímu dokumentovanému zdrojovému textu.
Dokumentační jazyk, kterým je psán obsah dokumentačních komentářů, je inspirován
několika jinými jazyky. Nejsilnější zdroj inspirace je zřejmě systém JavaDoc, který je standardním
systémem pro vytváření dokumentace ke zdrojovým textům v jazyce Java. Podobně jako v systému
JavaDoc je dokumentace dělena na logické oddíly zvané v systému DocSys sekce. Sekce je logický
oddíl pro popsání konkrétní věci, např. jedna sekce popisuje parametry funkce, jiná návratovou
hodnotu. Dalším rysem, k němuž inspiroval JavaDoc, je použití zkratek za časté či dlouhé
konstrukce, tzv. maker (v systému JavaDoc jsou tato makra nazývána taglety a jsou také silnější,
než makra v systému DocSys). Syntaxe jak sekcí, tak maker je prakticky totožná se syntaxí
v systému JavaDoc a bude popsána v dalších kapitolách.
Dokumentační jazyk systému DocSys je silně orientovaný na XML. Pro formátování textu
dokumentace a další efekty (vkládání odkazů, obrázků apod.) slouží XML tagy – proto se také
očekává, že uživatel má o XML alespoň základní povědomí, že zná pojmy tag, XML namespace a
ví, co je dobře formovaný XML dokument. Používání tagů (ať již HTML nebo XML tagů)
v dokumentačních jazycích je vcelku obvyklé (JavaDoc používá HTML tagy, dokumentace
v jazyce C# se píše s využitím HTML tagů). Tagy totiž jsou silný nástroj pro vyjádření téměř
libovolného formátování či struktury. Mají však i své stinné stránky – ruční značkování textu, bez
pomoci specializovaného editoru, je nepohodlné a zvlášť některé konstrukce jsou nepřehledné. To
je ovšem nepříjemné, pokud je takový text součástí zdrojových textů dokumentovaného díla a má
sloužit nejen jako zdrojový text pro nástroj, který z něj vygeneruje přehledný dokument, ale i jako
komentář pro programátora, který pracuje přímo se zdrojovými texty.
Aby nebylo nutné používat ve zdrojovém textu dokumentace tolik tagů, používá systém
DocSys odsazování jako syntaktický prostředek. Odsazování je schopné řadu tagů nahradit a
pomoci tak zpřehlednění zdrojového textu i usnadnit zápis dokumentace v obyčejném textovém
editoru. Mechanismus, kdy se odsazování stává částí syntaxe jazyka, je známý např.
z programovacího jazyka Haskell – tam je tento způsob zápisu označován jako layout-sensitive,
tento těžko přeložitelný termín se v systému DocSys bude nadále označovat zkráceně layout.
2.2 Struktura dokumentace
Systém DocSys byl navržen zejména pro vytváření dokumentace projektů psaných
v programovacích jazycích s hierarchickou strukturou prostoru jmen, mezi něž patří např. C++, C#,
Java nebo Object Pascal. Prvky této hierarchie (což mohou být třídy, metody, proměnné, funkce,
procedury atd.) se nazývají entity programovacího jazyka a jsou předmětem dokumentování. Každá
entita může mít připojenou dokumentaci v podobě dokumentačního komentáře. Systém DocSys pak
z těchto komentářů vygeneruje XML dokumenty, které propojí odkazy tak, aby byla zachována
hierarchická struktura entit ve zdrojovém textu. Dokument vygenerovaný z komentáře se nazývá
stránkou dokumentace a ke každé okomentované entitě existuje nejvýše jeden. Stránky jsou
obohaceny ještě o další údaje (např. deklarace entity v použitém programovacím jazyce) a jsou
vygenerovány i doplňkové XML dokumenty (např. abecední index všech zdokumentovaných entit).
4
Dokumentace entit tvoří tedy strom, který kopíruje hierarchii entit v programovacím jazyce,
ve kterém jsou implementovány. V jednom projektu může být použito i více programovacích
jazyků, každý z nich má vlastní hierarchii reprezentovanou vlastním stromem dokumentace – strom
dokumentace pro jeden konkrétní programovací jazyk se nazývá jazykový kontext. Souhrn všech
jazykových kontextů tvoří dokumentační strom.
2.3 Dokumentační komentáře
Jak bylo zmíněno, k entitám ve zdrojovém textu může programátor připojit dokumentaci
v podobě dokumentačního komentáře. Dokumentační komentář je komentář programovacího
jazyka, který obsahuje část zdrojového textu dokumentace (tzv. dokumentační blok) a který je od
ostatních, běžných komentářů odlišen několika speciálními znaky na svém začátku. Podle těchto
úvodních znaků systém DocSys rozpozná, že se má obsah komentáře interpretovat jako zdrojový
text dokumentace.
Způsob odlišení dokumentačního komentáře od běžných komentářů závisí na konkrétním
jazyku, ve kterém se komentář vyskytuje. Pro všechny dokumentační komentáře však platí:
1. Dokumentační blok musí být vložen do souvislého komentáře.
2. Pokud jazyk nedisponuje víceřádkovými komentáři, jsou víceřádkové dokumentační
komentáře emulovány jednořádkovými. Způsob emulace je definován pro konkrétní
jazyk s přihlédnutím k jeho specifickým vlastnostem.
3. Všechny konstrukce dokumentačního jazyka nezávislé na programovacím jazyce jsou
vždy case-sensitive.
Dokumentační bloky (obsahy dokumentačních komentářů) existují tří druhů:
•
Implicitní úplný blok – komentují entitu z libovolného jazykového kontextu, která je buď
explicitně zadána v dokumentačním bloku, nebo v případě chybějícího zadání bude
v aktuálním souboru (souboru, v němž se blok nachází) nalezena jako první po skončení
dokumentačního komentáře obsahujícího daný dokumentační blok.
•
Jednoduchý dopředný blok – komentuje entitu, která bude v aktuálním souboru nalezena
jako první hned po skončení dokumentačního komentáře obsahujícího daný
dokumentační blok; její absence je chyba.
•
Jednoduchý zpětný blok – komentuje entitu, která byla v aktuálním souboru nalezena
jako poslední před začátkem dokumentačního komentáře obsahujícího daný
dokumentační blok; její absence je chyba.
Příklad:
Aby si čtenář mohl udělat konkrétnější představu pojmů, které byly vyloženy, je tu uveden fragment
zdrojového kódu jazyka C++ s připojenou dokumentací v systému DocSys. Řádky jsou očíslovány a
okomentovány pod ukázkou.
5
(1) /**
(2) @
Funkce zkopíruje řetězec.
(3)
(4) @parameters
(5)
@{param "src"}
(6)
Ukazatel na null-terminated zdrojový řetězec.
(7)
(8)
@{param "dest"}
(9)
Ukazatel na buffer pro příjem zdrojového řetězce.
(10)
(11)
@returns
(12)
Funkce vrací ukazatel na cílový buffer.
(13)
(14)
@description
(15)
Zkopíruje řetězec @{id "src"} včetně ukončující nuly do bufferu
(16)
specifikovaného ukazatelem @{id "dest"}; cílový buffer musí být
(17)
dostatečně dlouhý a nesmí se překrývat se zdrojovým bufferem.
(18)
*/
(19)
char* strcpy(char* dest, const char* src);
(20)
(21)
//> Struktura pro uložení výsledku celočíselného dělení.
(22)
struct div_t {
(23)
int quot;
/// Podíl celočíselného dělení.
(24)
int rem;
/// Zbytek po dělení.
(25)
};
Řádek 19 obsahuje deklaraci funkce, řádky 22–25 struktury a 23–24 jejích členů; v příkladu jsou
tedy deklarovány čtyři entity, které dostanou jména strcpy(), div_t, div_t::quot,
div_t::rem; je tu i patrná hierarchie: strcpy() a div_t jsou na stejné úrovni, quot a rem jsou
členy div_t. Tato struktura se zachová i ve výsledné dokumentaci a na dokumentační stránce
k div_t budou automaticky zmíněny i quot a rem.
Řádky 1–18 tvoří dokumentační komentář, který je víceřádkový a obsahuje implicitní blok – to se
pozná podle jeho začátku, sekvencí /** začínají v C++ právě víceřádkové dokumentační komentáře.
Protože blok je implicitní a není nijak zadáno, ke které entitě se má vztahovat, vztahuje se k první
následující deklaraci, tedy k funkci strcpy().
Řádek 21 obsahuje jednořádkový komentář s dopředným blokem (sekvence //> je vyhrazena právě
pro takové komentáře). Tyto jednoduché komentáře mohou obsahovat jen stručný popisek a jsou
vlastně zkratkou za použití víceřádkového komentáře. Komentář na řádku 21 by bylo možné
ekvivalentně zapsat:
/** @ Struktura pro uložení výsledku celočíselného dělení. */
Řádky 23–24 obsahují jednořádkový komentář se zpětným blokem (sekvence /// je vyhrazena pro
tento druh komentářů). Chování obou druhů jednořádkových komentářů je analogické, i tento
jednořádkový komentář lze ekvivalentně zapsat pomocí úplného komentáře, např.:
/** <- @ Podíl celočíselného dělení. */
Význam použitých značek uvnitř komentáře i další podrobnosti budou vyloženy v následujícím textu.
6
3. Struktura
dokumentačního
bloku
V předchozí kapitole bylo vyloženo, co to je dokumentační blok, a zmíněno bylo, že jeho
obsahem je zdrojový text dokumentace, který je dělený na sekce. Též byly rozebrány typy
dokumentačních bloků – bloky jsou jednak jednoduché (dopředné a zpětné) a jednak úplné.
Jednoduché bloky jsou vlastně jen zkratkami pro zápis krátkých poznámek, a mají proto drobná
omezení, která budou zmíněna později. Následující text se tedy věnuje výkladu struktury a zápisu
úplného dokumentačního bloku.
Úplný dokumentační blok se skládá z metasekce a sekcí (sekce již byly zmíněny v minulé
kapitole). Metasekce, jejíž popis je hned v následujícím oddílu, bývá většinou prázdná (chybí) a
slouží jen pro speciální případy. Vlastní dokumentace je tedy soustředěna v sekcích, které budou
rozebrány hned po metasekci.
7
Terminologie:
Při výkladu syntaxe bude použit občas termín uvozovkovaný řetězec; tento termín označuje
textový řetězec uzavřený do rovných uvozovek (znak "), na jehož vnitřek jsou aplikována
následující pravidla:
1. Každý tabulátor je nahrazen jednou mezerou.
2. Každý konec řádku je nahrazen jednou mezerou.
3. Každá skupina mezer, kterou nelze prodloužit, je nahrazena jednou mezerou.
4. Každá dvojice (bráno zleva) rovných uvozovek (znak ") je nahrazena jednou uvozovkou.
5. Žádné jiné pravidlo se již neaplikuje (týká se implicitních pravidel, která vyplynou
z textu později).
Příklad:
Sekvence
"za čárkou následují dvě mezery,
a na závěr uvozovka"""
pak konec řádku
bude interpretována jako
za čárkou následují dvě mezery, pak konec řádku a na závěr uvozovka"
3.1 Metasekce
Metasekce je oblast dokumentačního bloku před začátkem první sekce. Obsahuje data, která
určují atributy dokumentačního bloku a řídí jeho chování.
Obsah metasekce:
[["(jazykový kontext)"] "(plné jméno entity)" | -> | <- ] [display="(popisek
entity)"]
Pořadí dat je závazné. První dvojice atributů udává jednoznačně entitu programovacího
jazyka, k níž se má dokumentační blok vázat a musí být přítomna, právě tehdy když blok není
vázán pozicí ve zdrojovém souboru k následující či předchozí entitě. Vázání pozicí lze provést
„šipkami“ (následující či předchozí), pokud chybí explicitní zadání entity i „šipky“, je implicitní
vazba dopředná (odpovídá „šipce“ vpravo). Pokud je použito vícero zadání vazby, je to chyba.
Neuvedená hodnota pro jazyk znamená použití jazyku aktuálního souboru.
Atributy musí být uvedeny v podobě uvozovkovaných řetězců, prázdné hodnoty pro jazyk a
atribut display jsou brány jako neuvedené.
Atribut display není povinný a jeho implicitní hodnota je rovna (zkrácenému, ne plně
kvalifikovanému) jménu entity. Jeho hodnota představuje popisek, který se má použít pro titulek
dokumentu k dané entitě či pro zobrazení popisku entity v programu zpracovávajícím dokumentační
komentáře a nemusí nijak souviset se jménem entity.
8
Příklad:
Mějme projekt, ve kterém je použit jazyk C++ i Pascal. Následující komentář v jazyce C++ bude
svázán s pascalovskou procedurou Copy() z unity System, protože vazba k entitě byla zadána
explicitně včetně jazyka.
/** "Pascal" "System.Copy()" @ Funkce zkopíruje řetězec. */
Analogicky pokud by úvodní příklad začínal následujícím fragmentem, nemusel by komentář
k funkci strcpy() být bezprostředně před její deklarací, ale v libovolném jiném zpracovaném
zdrojovém souboru jazyka C++:
/** "::strcpy()"
@
...
Kdybychom chtěli, aby deklarace funkce strcpy() předcházela jejímu dokumentačnímu
komentáři, můžeme to učinit následovně pomocí zpětné „šipky“ v metasekci:
char* strcpy(char* dest, const char* src);
/** <@
...
3.2 Sekce
Sekce představuje samostatnou jednotku dokumentačního bloku; tato jednotka představuje
malý tematický blok (např. jedna sekce je věnována popisu parametrů, druhá popisu návratové
hodnoty atd.). Každá sekce má přiřazené jméno s výjimkou anonymní sekce, jejíž jméno je prázdné.
Jméno sekce by mělo být unikátní v rámci dokumentačního bloku, speciálně anonymní sekce může
být nejvýše jedna. Jméno sekce se musí skládat pouze z písmen malé a velké anglické abecedy,
podtržítka a číslic 0–9; číslice se nesmí vyskytovat jako první znak jména.
Sekce končí začátkem následující sekce nebo koncem dokumentačního komentáře. Začátek
nové sekce je uvozen znakem zavináč (znak @), za nímž bezprostředně následuje jméno sekce,
které je od obsahu sekce nebo následující sekce (v případě prázdné sekce) odděleno bílým znakem
(mezera, tabulátor, konec řádku).
Předdefinováno je několik standardních sekcí. Jejich úplný výčet a účel jednotlivých sekcí je
uveden v samostatné kapitole.
Příklad:
V úvodním příkladu je v komentáři k funkci strcpy() hned několik sekcí: anonymní (2),
parameters (4), returns (11) a description (14).
9
3.3 Jednoduché bloky
Na začátku kapitoly byly zmíněny jednoduché bloky. Jednoduché bloky jsou zkratkami za
úplné bloky, které by obsahovaly pouze anonymní sekci a byly vázány svou pozicí na následující
nebo předchozí entitu. Jednoduché bloky jsou buď dopředné nebo zpětně – to je zadáno už
samotným tvarem značky komentáře, který blok obsahuje. Díky tomu jednoduchý blok nepotřebuje
metasekci a jeho obsah je přímo obsahem anonymní sekce, jak už bylo naznačeno v úvodní ukázce
(jednoduché bloky byly použity na řádcích 21–24). Jiné sekce než anonymní nemůže jednoduchý
blok obsahovat. Díky své jednoduchosti je vhodný k popisům datových položek strukturovaných
datových typů apod., kde charakteristika bývá omezena na několik málo slov.
10
4. Zápis obsahu
sekce
Jazyk pro dokumentaci z části kopíruje rysy XML – převzata je myšlenka značkování textu
XML značkami (XML tagy), zcela jsou převzaty vestavěné XML entity. Nové je zavedení tzv.
layoutu, což je mechanismus, kdy odsazování textu má syntaktický význam. Layout má význam pro
zpřehlednění zdrojového textu dokumentace a redukci použití XML tagů.
Doplnění textu značkovaného po způsobu XML o layout a potřeba snadné návaznosti na
HTML zavádí některá opatření a omezení, která XML samo nemá. Zdůraznit se musí zejména
odlišné nakládání s bílými znaky, jiná citlivost řídících znaků, existence několika speciální značek a
case-sensitivity jmen tagů i jejich atributů. Dále je třeba zdůraznit fakt, že tagy musí být párovány a
musí být párovány uvnitř sekce (tedy tag nesmí být otevřen v jiné sekci, než ve které je uzavřen).
Zpracování řídících znaků a layoutu a také zpracování maker je předmětem této kapitoly a
popsáno v následujících oddílech.
11
4.1 Makra
Makra jsou jednoduché parametrizované textové náhrady sloužící jako zkratky. Makra se
smí používat pouze v textu sekcí, jsou zpracovávána samostatně a výsledek jejich expanze je vložen
do výsledné dokumentace zbavený krajních mezer. Pokud makro obsahuje tag, nesmí obsahovat jen
jeho část. Pokud makro obsahuje speciální tagy link a obj (o kterých bude řeč v následující
kapitole), musí být tyto tagy v rozvoji makra i uzavřeny.
Syntaxe volání makra:
@{macro_name ["(argument 1)" ["(argument 2)" ... ]]}
Argumenty jsou interpretovány jako uvozovkované řetězce a expanze makra se může lišit
podle počtu použitých argumentů (tedy makra jsou přetížena počtem argumentů).
Předdefinováno je množství standardních maker. Standardní makra využívají pouze
standardní tagy. Výčet standardních maker je uveden v samostatné kapitole až po výkladu
standardních tagů.
Příklad:
Příkladem použití makra může být opět úvodní ukázka – na řádcích 5 a 8 je volání makra param,
na řádcích 15 a 16 makra id (obě makra jsou jednoparametrická).
Příklad:
Budiž macro makrem, které se expanduje na řetězec ABC.
<@{macro}> je chybné použití – pokus o vytvoření tagu ABC nevyjde, makro se totiž zpracovává
samostatně.
Bude-li mít macro obsah <ABC, nejedná se též o korektní situaci: makro neobsahuje celý tag.
Příkladem dobře definovaných maker, jejichž používání bude vždy v pořádku, jsou standardní
makra, která jsou popsána v samostatné kapitole.
4.2 Layout
Na značkování textu sekce se podílí formátování zdrojového textu dokumentace
odsazováním – tento mechanismus se nazývá layout. Blok zdrojového textu dokumentace
zarovnaného levým okrajem na stejný sloupec bez prázdných řádků (resp. řádků pouze z bílých
znaků) tvoří paragraf. Dva paragrafy mohou být odděleny rozdílnou indentací nebo prázdným
řádkem mezi sebou. Znak tabulátoru se vždy uvažuje jako osm mezer; z tohoto důvodu je vhodné
používat pro odsazování buď striktně mezery, nebo tabulátory.
Čistý text paragrafu vznikne spojením řádků paragrafu a nahrazením každé skupiny bílých
znaků jednou mezerou (podobně jako v HTML). Případné bílé znaky na začátku a konci takto
získaného textu jsou také odstraněny. Tím je z textu paragrafu odstraněn vliv jeho odsazení a také
jsou odstraněny znaky zalomení řádku včetně zalomení posledního řádku paragrafu.
12
Příklad:
Toto je text prvního paragrafu. Přesněji zde je jeho první řádek
a zde již druhý. Řádky paragrafu budou ve výsledku spojeny za sebe,
takže výsledek bude přirozený a za čárkou na konci předchozího řádku
bude mezera, jak je obvyklé.
Druhý paragraf začíná zde – první dva pragrafy jsou odděleny prázdným
řádkem. Následující paragraf bude oddělen odlišnou indentací.
Zde je zmíněný třetí paragraf, který je od druhého oddělen jinou
úrovní odsazení.
Zde byla skupina mezer – ta bude ve výsledku
zredukována na jedinou, takže za tečkou zůstane pouze jedna.
Příklad:
Když použijeme opět úvodní ukázku, zjistíme, že první dokumentační komentář obsahuje celkem
sedm paragrafů (začínají na řádcích: 2, 5, 6, 8, 9, 12 a 15).
Pro explicitní ovlivňování layoutu existují dva speciální tagy nazývané layout-marks. Oba
tyto tagy jsou nepárové, resp. párové samy k sobě. První z nich zapisovaný <//> (break-mark) ruší
detekci následujícího paragrafu. Sám musí být na konci řádku, pokud není, je ignorován.
Druhý layout mark se zapisuje </> (para-mark) a je opakem k break-mark; ukončuje násilně
aktuální paragraf a od jeho pozice se okamžitě začíná hledat další paragraf.
Příklad:
Text prvního paragrafu.</>
Text druhého paragrafu, ač by tu být ještě podle odsazení druhý paragraf
neměl. Tento způsob zápisu šetří místo zejména v tabulkách nebo seznamech. Pak
je totiž pak možné vložit dva paragrafy vedle sebe na jeden řádek. Jinde než
v tabulkách by se to ale užívat příliš nemělo, protože to narušuje přehlednost
textu a jeho členění. </> A zde už je třetí paragraf. Nutné ovšem
poznamenat, že se musí držet svého
levého okraje.
Text čtvrtého paragrafu, do kterého je vložena HTML tabulka – není to DocSys
tag a nepracuje s paragrafy, tedy nelze pro něj užít přínos layoutu, naopak je
vhodné implicitní fungování layoutu potlačit:<//>
<html:table><//>
<html:tr><html:td>První buňka HTML tabulky; díky break-marks bude tabulka
naformátována ve zdrojáku vždy hezky</td><//>
<html:td>Druhá buňka tabulky. Ale stále je celá tabulka díky break-marks
v jednom odstavci a nerozpadne se kvůli layoutu. Nutné je ovšem správně
doplňovat break-marks.</html:td></html:tr><//>
</html:table><//>
Význam layout-marks bude zvlášť patrný, jakmile bude popsán seznam standardně
podporovaných tagů a jejich možnosti.
4.3 Zpracování řídících znaků
Způsob zpracování bílých znaků byl již popsán v předchozím oddíle věnovaném layoutu –
popsaný postup vede k tomu, že text paragrafů neobsahuje nadbytečné bílé znaky.
13
Protože dokument je založený na XML, lze užít pro vkládání speciálních znaků XML entity.
Speciálně řídící znaky musí být escapovány na místech, kde by měly svůj speciální význam, mají-li
být považovány za obyčejné znaky bez zvláštního významu.
Poznámka:
Pro některé z následujících znaků existují předdefinované entity v HTML (např.  
pro nevypustitelnou mezeru nebo " pro uvozovku) – ty však nejsou přímo v XML
definované a nelze je použít v zápisu komentářů. Naštěstí tyto znaky není typicky třeba
vkládat tak, aby bylo nutné je escapovat.
Znak " (rovná uvozovka)
Pro tento znak platí, že formuje uvozovkovaný řetězec pouze tam, kde podle syntaxe je
očekáván. Dovnitř uvozovkovaných řetězců se vloží svým zdvojením. V ostatních případech se
chová stejně jako v XML (a lze jej nahradit XML entitou ").
Znak & (ampersand)
Escapuje se XML entitou & (ekvivalentní je &). Interpretuje se jako řídící znak
všude mimo uvozovkované řetězce. Z toho také vyplývá, že uvnitř uvozovkovaných řetězců nelze
používat náhrady XML entitami – s výjimkou uvozovek ztrácejí v uvozovkovaných řetězcích své
speciální postavení všechny nebílé znaky.
Znak < (menší než)
Mimo uvozovkované řetězce se chová stejně jako v XML, tedy je řídícím znakem, není-li
escapován. Escapuje se XML entitou < (ekvivalentní je <).
Znak @ (at-sign, zavináč)
Má význam všude mimo uvozovkované řetězce (interpretuje se jako začátek další sekce
nebo jako volání makra, následuje-li levá složená závorka). Escapovat lze XML entitou @
nebo standardním makrem @{at}.
Znak pro tvrdou mezeru
Má-li být vložena někde mezera, která nebude odstraněna při nahrazování skupiny bílých
znaků jedním, použije se XML entita   (stejně jako v HTML). Escapovat lze i standardním
makrem @{sp}.
14
5. Standardní tagy
Hlavní roli při zápisu formátování dokumentace hrají XML tagy. Layout je jen pomocné
opatření, které snižuje potřebu XML tagy používat a může snížit nepřehlednost některých
konstrukcí. S výjimkou několika málo speciálních tagů jsou si všechny tagy použité ve zdrojovém
textu rovnocenné. Standardní tagy popsané v této kapitole se liší od ostatních tagů pouze tím, že
mají předdefinováno další zpracování, které jim dodává sémantiku, zatímco použití a zpracování
nestandardních tagů si musí ošetřit uživatel sám – to je také důvod, proč by se uživatel měl vyhýbat
použití nestandardních tagů.
Pro zpracování všech tagů použitých ve zdrojovém textu platí několik jednoduchých
pravidel.
1. Všechny tagy definované systémem DocSys (standardní uživatelské i interní pomocné)
se nacházejí vždy v XML namespace docsys, jiné tagy než standardní z toho namespace
by uživatel neměl používat. Namespace docsys je implicitní; pokud tag nemá ve
zdrojovém textu uvedený žádný namespace, je pro další zpracování automaticky doplněn
o namespace docsys (a tedy se ve výsledném XML dokumentu objeví plně
kvalifikovaný).
2. Tagy ve zdrojovém textu, které se nacházejí v namespace nondocsys, budou ve
výsledném XML dokumentu tohoto namespace zbaveny. Díky předchozímu bodu
nedojde ke kolizi se standardními tagy.
15
3. Ostatní tagy, které mají ve zdrojovém textu uveden jiný namespace než docsys nebo
nondocsys, nejsou nijak modifikovány a jsou ponechány ve výsledném XML dokumentu
v původním tvaru.
Příklad:
Mějme fragment zdrojového textu dokumentace.
Toto je <b>tag, který má implicitně namespace docsys</b>.
<docsys:b>Zde je jeho ekvivalentní varianta.</docsys:b>
Tento <nondocsys:b>tag není standardním tagem, ale má být bez
namespace.</nondocsys:b>
Ani tento <html:b>tag není standardním tagem – namespace se mu však
zachová.</html:b>
Jeho podoba po aplikaci uvedených pravidel bude následující.
Toto je <docsys:b>tag, který má implicitně namespace docsys</docsys:b>.
<docsys:b>Zde je jeho ekvivalentní varianta.</docsys:b>
Tento <b>tag není standardním tagem, ale má být bez namespace.</b>
Ani tento <html:b>tag není standardním tagem – namespace se mu však
zachová.</html:b>
Definována je široká paleta standardních tagů, ale uživatel má možnost vložit do výsledných
XML dokumentů libovolné vlastní tagy, jak vyplývá z výše uvedeného. Interpretace těchto
nestandardních tagů závisí pouze na uživatelském zpracování.
5.1 Speciální tagy
Speciální tagy mají výsadní postavení ve zpracování nebo mají zvláštní význam. Jsou to
tagy link, obj, code a para (implicitní namespace docsys u nich bude vynecháván).
5.1.1 Paragrafy a tag para
Syntaxe:
<para>[(obsah paragrafu)]</para>
Tag para by uživatel neměl běžně používat, má totiž úzký vztah k layoutu. Layout je
fakticky jen jiný způsob značkování textu pomocí tagů para. Paragraf definovaný layoutem se
chová stejně, jako kdyby bez použití layoutu byl jeho obsah uzavřen v tagu para – až na drobnou
výjimku: layout není tak striktní jako značkování, tedy pokud ostatní tagy by bránily nasazení para
tagu (došlo by k jejich překřížení a výsledek by nebyl dobře formovaný XML dokument), mohou
být paragrafy layoutu interpretovány jako spojené.
16
Příklad:
Mějme fragment zdrojového kódu s využitím layoutu.
odstavec 1 <a-tag>
odstavec 2 <b-tag>
odstavec 3 </b-tag>
</a-tag> odstavec 4
Bez použití layoutu, kdy efekt dodaný layoutem je nahrazen aplikací tagu para, vypadá předchozí
ukázka následovně.
<docsys:para>odstavec 1 <a-tag>
<docsys:para>odstavec 2 <b-tag> odstavec 3 </b-tag></docsys:para>
</a-tag> odstavec 4</docsys:para>
V příkladu je vidět spojení druhého a třetího odstavce, aby nedošlo k překřížení značky <b-tag>
s tagem para. Čtvrtý odstavec nesmí být uzavřen do tagu para, ale může jím být ukončen, protože
</a-tag> ukončí párováním s <a-tag> narušující dvojici.
Příklad:
Opět je uveden fragment zdrojového kódu s využitím layoutu:
odstavec 1 <a-tag><b-tag>
odstavec 2 </b-tag>
odstavec 3 </a-tag>
odstavec 4
A bez něj s použitím tagů para:
<docsys:para>odstavec 1 <a-tag><b-tag>odstavec 2 </b-tag>odstavec 3 </atag></docsys:para>
<docsys:para>odstavec 4</docsys:para>
Jak je z příkladů vidět, spojování odstavců může vypadat nepřirozeně. Je tedy uživateli doporučeno
párovat tagy uvnitř odstavců. Pokud nějaký tag zahrnuje více odstavců, měl by být otevřen na konci
odstavce a zavřen na začátku jiného odstavce. Tagy přes více odstavců jsou povoleny, aby bylo
možné dělat snadno konstrukce založené na odstavcích a layoutu, jako je např. tag table2 (bude
popsán přesně ve výčtu nespeciálních standardních tagů):
Odstavec obsahuje tuto tabulku hodnot: <table2 header1="Hodnota"
header2="Popis">
První hodnota
Popisek první hodnoty.
Druhá hodnota
Popisek druhé hodnoty.
</table2>Zde pokračuje odstavec.
17
Ve výsledném XML dokumentu se předchozí konstrukce objeví v tomto tvaru:
<docsys:para>Odstavec obsahuje tuto tabulku hodnot: <docsys:table>
<docsys:tr style="header">
<docsys:td>Hodnota</docsys:td>
<docsys:td>Popis</docsys:td>
</docsys:tr>
<docsys:tr>
<docsys:td>První hodnota</docsys:td>
<docsys:td>Popisek první hodnoty.</docsys:td>
</docsys:tr>
<docsys:tr>
<docsys:td>Druhá hodnota</docsys:td>
<docsys:td>Popisek druhé hodnoty.</docsys:td>
</docsys:tr>
</docsys:table>Zde pokračuje odstavec.</docsys:para>
Ačkoliv je nutné používat layout opatrně (viz předchozí příklady), ukazuje tento příklad, jak moc
layout dovede ulehčit zápis např. tabulek, ale i různých seznamů. Při správném použití
standardních tagů navržených pro spolupráci s layoutem se z něj stává mocný nástroj.
5.1.2 Tagy link a obj
Syntaxe:
<obj [[lang="(jazykový kontext)"] target="(jméno entity)"]>[(text
odkazu)]</obj>
<link [[lang="(jazykový kontext)"] target="(jméno entity)"]>[(text
odkazu)]</link>
Značky link a obj slouží k vložení odkazu na jiný dokumentační blok. Atribut lang
specifikuje jazyk (jazykový kontext) odkazované entity, atribut target je odkaz na entitu v daném
jazykovém kontextu. Hodnoty obou jejich atributů nejsou ve formě hodnot klasických XML
atributů (řetězec uzavřený v uvozovkách, v němž fungují náhrady XML entitami), ale jejich
hodnota je tvořena uvozovkovaným řetězcem (viz terminologickou poznámku ze 3. kapitoly). Pro
chování obou těchto tagů platí:
1. Pokud chybí atribut lang, užije se jazykový kontext, v němž se komentovaná entita
nachází.
2. Pokud chybí atribut target, jedná se o odkaz na rodičovský uzel; v tomto případě musí
chybět i atribut specifikující jazyk.
3. Pokud chybí tělo tagu, užije se pro text odkazu metaatribut display odkazovaného uzlu.
V případě, že by chyběl text pro tag i v tomto případě, může být použit pro text přímo
atribut target.
4. Celý tag musí být obsažen v jednom paragrafu (nesmí tedy ani obsahovat para-mark) a
nesmí obsahovat jiný tag link nebo obj.
Rozdíl mezi značkami link a obj je takový, že pokud při vytváření XML cíl odkazu není
nalezen, je v případě tagu link oznámena uživateli chyba, v případě tagu obj je nenalezení cíle tiše
ignorováno a vložený odkaz je slepý, nejde použít.
18
Obsah tagů (text odkazu) by měl být prostý text – pokud se v obsahu tagu vyskytují makra či
jiné tagy, makra budou korektně expandována a tagy vloženy do výsledného XML dokumentu,
korektnost takového výsledku závisí na jeho konkrétním obsahu a dalším zpracování.
5.1.3 Tag code
Syntaxe:
<code[#(escape signatura)]>(neformátovaný text)</code[#(escape signatura)]>
Tag code je speciální tag pro vložení neformátovaného textu, se kterým se nakládá jinak než
s ostatním (běžným) textem sekce. Zásadním způsobem mění zpracovávání zdrojového textu
dokumentace a potlačuje aplikaci layoutu. Jeho syntaxe je odlišná od regulérních XML tagů
v souladu s jeho určením a stejně tak platí zvláštní pravidla pro jeho použití – obsah vložený tagem
code do výsledného XML dokumentu bude ovlivněn těmito třemi pravidly:
1. Na řádku s otevíracím tagem code se ignoruje text za tagem, až do konce řádku, je-li celý
z bílých znaků; pokud je posledním znakem obsahu tagu (nefomátovaného textu) konec
řádku, je tento poslední znak také ignorován.
2. V těle tagu nejsou rozpoznávány žádné značky, entity ani jiné objekty, veškeré řídící
znaky ztrácejí svůj speciální význam; ukončení tohoto režimu je možné pouze koncovým
tagem code se stejnou escape signaturou, který byla použita u otevíracího tagu. Zápis
tagu code se liší od zápisu ostatních tagů a je mnohem striktnější.
3. Bílé znaky v obsahu tagu od sloupce paragrafu, v němž se tag code nachází, až po první
nebílý znak se zachovávají. Zachovává se též konec řádku (nepřekládá se na mezeru jako
v běžném textu sekce).
19
Příklad:
Ukázka obsahuje fragment s ukázkou vloženého příkladu zdrojového textu.
Následuje malá ukázka zdrojového textu; speciálně za povšimnutí
stojí fakt, že ukázka obsahuje znaky, které mají řídící význam
v běžném textu sekce. Díky tagu code nebudou interpretovány.
Ukázka kódu (schválně je tu použito odsazení, mezery na začátku
řádku až po sloupec paragrafu, na kterém se nachází tag code,
budou ignorovány):
<code#Escape>
#include <stdio.h>
void foo(int& ref) {
if (ref) ref--;
}
int main(int argc, char* argv[]) {
foo(argc);
printf("Tento program nedělá nic rozumného.\
Kontaktujte autora na [email protected].");
return argc;
}
</code#Escape>
Text, který bude načten z obsahu tagu code, vypadá takto:
#include <stdio.h>
void foo(int& ref) {
if (ref) ref--;
}
int main(int argc, char* argv[]) {
foo(argc);
printf("Tento program nedělá nic rozumného.\
Kontaktujte autora na [email protected].");
return argc;
}
Upozornění:
Speciálně u tagu code je nutné zdůraznit to, co platí v celém dokumentačním komentáři:
text dokumentace je uzavřen v komentáři a řetězce, které by ukončily komentář, je nutné
escapovat – uvnitř tagu code však escapovat nelze!
5.2 Běžné tagy
Tagy popsané v tomto oddíle jsou vlastně obyčejné XML tagy, které jen mají
předdefinované zpracování; díky tomuto zpracování mnohé z nich spolupracují s layoutem.
20
5.2.1 Jednoduché seznamy
Syntaxe:
<item [caption="(popisek položky)"] />
(seznam paragrafů pro jednu položku)
...
<itemstop />
Jednoduché seznamy lze vytvářet pomocí tagu item a itemstop. Tyto seznamy se užívají
pouze na úrovni sekce a nelze je vnořovat, pro mnohé však postačují – např. popis argumentů
funkce, návratových hodnot apod. Jejich omezení jsou kompenzována snadným užitím: tag item
vytvoří pojmenovanou položku seznamu, jejíž obsah tvoří všechny následující paragrafy až do
dalšího výskytu tagu item, seznam je ukončen koncem sekce nebo tagem itemstop. Fakticky se
tento seznam chová podobně jako sekce.
Každý tag item či itemstop se má nacházet v samostatném paragrafu, protože zbytek
paragrafu, ve kterém se nachází, bude zahozen a jejich obsah ztracen. Není totiž příliš dobře jasné,
jak s obsahem těchto tagů naložit.
Příklad:
Jednoduchý seznam můžeme vytvořit např. takto:
<item caption="První položka" />
Zde se napíše obsah první položky. Ve výsledku bude tomuto
odstavci předsazen zvýrazněný popisek.
Toto je další paragraf, ale stále spadá pod první položku
seznamu.
<item caption="Druhá položka" />
A tady už začíná druhá položka.
<item caption="Ztracený text" /> Pokud bude text ve stejném paragrafu,
jako tag item nebo itemstop, bude ztracen – takto to nepoužívejte!
<itemstop />
Tento paragraf už nespadá do seznamu, seznam byl ukončen tagem
itemstop. Seznam je automaticky též ukončen koncem sekce,
v takových případech tedy není nutné itemstop použít.
5.2.2 Pokročilejší seznamy
Syntaxe:
<list [style="(jméno stylu)"]>
[(seznam paragrafů)]
</list>
Tag list dovoluje vytvářet složitější seznamy, dokonce i zanořované. Položkami seznamu
jsou paragrafy, tedy není žádný tag pro vytvoření položky seznamu, stará se o to layout. Atribut
style určuje styl seznamu, standardně jsou definovány tyto hodnoty:
21
bullets
numbers-alpha
numbers-decimal
numbers-roman
plain
tree
Implicitní styl, který představuje seznam s kulatými odrážkami.
Seznam číslovaní písmennou řadou.
Seznam číslovaný decimálními čísly.
Seznam číslovaný římskými čísly.
Pouze uspořádává položky, nemá žádné odrážky.
Vykresluje seznam jako jednu úroveň stromu (s pomocí odsazení).
Příklad:
Následující ukázka vytvoří číslovaný seznam se dvěma úrovněmi.
<list style="numbers-decimal>
Toto je první položka číslovaného seznamu, která bude označena
číslem 1.
Toto je druhá položka číslovaného seznamu, která bude označena
číslem 2. Tato položka má ještě podpoložky:<//>
<list style="numbers-alpha">
Podpoložka a) položky 2.
Podpoložka b) položky 2.
</list>
</list>
Za povšimnutí stojí použití <//> (break-mark), který umožní odsadit vnořený tag list do dalšího
paragrafu, avšak logicky oba bloky tvoří jeden, spojený právě pomocí break-mark. Vnořený seznam
drží pohromadě díky pravidlům o slepování paragrafů: <list> a </list> musí být v jednom logickém
paragrafu, aby výsledkem byl dobře formovaný XML dokument. Tato technika je použita i u
následujících tagů, zde tedy ještě bude ukázáno, jak by vypadala předchozí ukázka, kdyby layout
nahradilo čistě používání tagů para. U ostatních tagů to již pro stručnost ukazováno nebude.
<para><list style="numbers-decimal>
<para>Toto je první položka číslovaného seznamu, která bude označena
číslem 1.</para>
<para>Toto je druhý položka číslovaného seznamu, která bude označena
číslem 2. Tato položka má ještě podpoložky:
<list style="numbers-alpha">
<para>Podpoložka a) položky 2.</para>
<para>Podpoložka b) položky 2.</para>
</list></para>
</list></para>
5.2.3 Tabulky s pevným počtem sloupců
Syntaxe:
<table(N = číslice 1–5)
[style="(jméno stylu)"]
[header(číslice v intervalu 1 – N včetně)="(popis sloupce) ...]>
[(seznam paragrafů, které tvoří obsah tabulky)]
</table(N)>
22
Nejpoužívanější jsou tabulky s pevným počtem sloupců; předdefinovány jsou tagy pro
tabulky s jedním až pěti sloupci. Pokud by uživatel potřeboval více sloupcí, může užít obecnou
tabulku popsanou dále. Tabulky je možno i vnořovat a kombinovat.
Tabulka je vyplňována buňku za buňkou postupně zleva doprava a shora dolů. Obsahem
buňky je jeden paragraf. Záhlaví tabulky lze nadepsat pomocí atributů header (header1 je první
sloupec atd.). Styl tabulky je zadán atributem style; implicitním stylem je basic, který je
momentálně jedinou definovanou hodnotou.
Příklad:
Ukázka obsahuje dvě tabulky, jednu se dvěma sloupci, druhou se třemi; při používání tabulek se
předpokládá právě nejvíc používání tabulek se dvěma sloupci – ty se hodí pro výčty konstant apod.
Ve druhé tabulce (se třemi sloupci) je pro koncentrování zápisu použit tag </> (para-mark), aby
nebylo nutné měnit odsazení nebo vynechávat řádek pro jediné číslo. Tímto způsobem lze
koncentrovat zápis zejména tabulek. Para-mark lze používat i násobně na řádku, jak je vidět u
posledních dvou řádků druhé tabulky.
<table2 header1="Konstanta" header2="Popis">
O_APPEND
Zápis bude veden na konec souboru (tedy bude do souboru
pouze připisováno).
O_CREAT
Vytvoří a otevře nový soubor. Nemá efekt při použití na
existující soubor.
O_TRUNC
Otevře existující soubor a zkrátí jeho délku na nulu; k souboru
musí být právo zápisu. Jeho obsah při zkrácení zničen.
</table2>
<table3 header1="Konstanta" header2="Popis" header3="Hodnota">
INT_MIN
Minimální hodnota pro proměnnou typu int.</>
-2147483647 – 1
INT_MAX
Maximální hodnota pro proměnnou typu int.</>
2147483647
UINT_MAX
Maximální hodnota pro proměnnou typu unsigned int.</>
4294967295 (0xFFFFFFFF)
ZERO
ONE
</table3>
</>
</>
Prostě nula.
Jednička.
</>
</>
0
1
</>
23
5.2.4 Tabulka s proměnným počtem sloupců
Syntaxe:
<tablen [style="(jméno stylu)"]>
[<headrow>
(paragrafy tvořící záhlaví tabulky)
</headrow>]
[<row>
(paragrafy tvořící řádek)
</row>]
...
</tablen>
Tabulka tablen je jen drobným rozšířením tabulek s pevným počtem sloupců. Tagy headrow
a row má vyznačeny své řádky, buňky na řádku jsou vyplňovány zleva doprava paragrafy. Tag
headrow uzavírá buňky, které mají být na řádku zobrazeném stylem záhlaví (může to být např. jiné
pozadí než zbytku tabulky apod.). Tag row slouží pro obyčejné řádky.
Příklad:
Tabulka v příkladu má dva řádky, první ve stylu záhlaví a se dvěma sloupci, druhý obyčený se
čtyřmi sloupci.
<tablen>
<headrow>
První buňka záhlaví.
Druhá buňka záhlaví.
</headrow>
<row>
První buňka.
Třetí buňka.
</row>
</tablen>
</>
</>
Druhá buňka
Čtvrtá buňka.
</>
5.2.5 Jednoduché formátovací tagy
Pro účely běžného formátování textu je dána sada jednoduchých tagů (všechny shodně
bezparametrické a ovlivňující text, který uzavírají):
b
i
u
id
kw
spec
sym
tt
val
24
Tučné písmo.
Kurzíva.
Podtržení textu.
Text je zvýrazněn jako identifikátor.
Text je klíčové slovo.
Obsahuje speciální symbol (např. rozšířené nestandardní klíčové slovo).
Zvýrazní text jako symbol.
Neproporcionální písmo.
Text je hodnota.
Tagy id, kw, spec, sym a val se užívají hlavně v automaticky generované sekci s deklarací
komentované entity pro zvýraznění syntaxe v deklaraci, ale lze čekat, že tagy id a val budou hojně
užívány i uživatelem v ostatních sekcích.
5.2.6 Vkládání externích odkazů
Syntaxe:
<img target="(odkaz)" />
<ximg target="(odkaz)" />
Tagy img a ximg slouží k vkládání obrázků do dokumentu. Atribut target udává jméno
souboru s obrázkem, který se má na místě tagu zobrazit. V případě tagu img je odkazem URL
(může odkazovat na web či lokální soubor na disku) a doporučeno je, aby URL bylo absolutní. Tag
ximg se odkazuje do tzv. ximg-repository, což je adresář zadaný v konfiguraci systému DocSys,
obsahující grafiku právě pro odkázání tagem ximg. Výhodou je, že takový odkaz je pouze relativní
a relativní může být i ve výsledku.
Syntaxe:
<xlink target="(odkaz)">(text odkazu)</xlink>
Tag xlink je obdobou tagu ximg. Rozdíl je však v tom, že jeho cílem není vložit do
dokumentu grafiku, ale pouze odkaz na libovolný soubor (např. archív ke stažení), který se nachází
v xlink-repository (analogie ximg-repository).
Syntaxe:
<url target="(odkaz)">(text odkazu)</url>
Pro vložení odkazu ve formě libovolného URL existuje tag url. Odkaz by se měl
v konečném dokumentu zobrazit podobně jako odkaz v HTML, a pokud to formát a aplikace
dovoluje, měl by být aktivní.
5.2.7 Ostatní běžné tagy
Všechny zbývající běžné tagy jsou bezparametrické a nemají žádné tělo. Jsou to date, time a
br. První dva vkládají datum (date) a čas (time), kdy byla dokumentace vytvořena.
Tag br představuje zalomení řádku. Běžně se text člení na odstavce dané layoutem.
V případě, že uživatel chce zalomit řádek ručně, může použít tento tag. Doporučeno je ho
kombinovat s tagem <//> (break-mark) pro spojení paragrafů. Pro tuto kombinaci existuje
standardní makro (makro @{br}, viz následující kapitola).
25
5.3 Méně běžné standardní tagy
Během transformace zdrojového textu dokumentace do XML dokumentu musí nutně dojít
k operaci, při které je layout nahrazen tagy (konkrétně tagy para). Dokument v takovém tvaru by
byl ale „nehezký“ a jeho struktura i sémantika by nebyla dobrá. Dojde tedy k jeho úpravám, při
kterých se běžné standardní tagy zkonvertují do množiny obecnějších tagů. Těch je méně a mají
komplikovanější syntaxi, aby pokryly všechny případy. Tyto tagy už nevědí nic o layoutu a neumějí
ho používat – jsou to však normální XML tagy, uživatel je tedy může použít při zápisu
dokumentace stejně jako kterékoliv jiné. Jejich používání není tak jednoduché (zvlášť nemají-li
kolidovat s layoutem), proto není doporučeno je používat, pokud postačují běžné standardní tagy.
Mezi tyto méně běžné tagy svým chováním patří do jisté míry i již zmiňovaný speciální tag para.
5.3.1 Obecná tabulka
Syntaxe:
<table [style="(styl tabulky)"]>
[<tr [style="(styl řádku)]>
[<td>(text buňky)</td> ...]
</tr> ...]
</table>
Skupina tagů table, tr a td slouží k zápisu obecné tabulky. Jejich syntaxe je shodná se
stejnojmennými tagy HTML tabulek, nemají však jejich atributy. Jediným atributem je style, který
představuje buď styl tabulky (zatím definován jen basic, který je implicitní) nebo řádku (zatím
definován table-header, který představuje záhlaví tabulky).
Příklad:
Jako příklad je uvedeno srovnání zápisu dvousloupcové tabulky pomocí layoutového tagu table2 a
pomocí jeho nelayoutového zobecnění table. Fragmenty budiž zapsány v dokumentačním jazyce,
tedy pokud varianta s použitím tagu table nemá tvořit jediný řádek a má vypadat aspoň trochu
přehledně, musí být použit často tag <//> (break-mark). Odmyslíme-li si použití break-marks,
získáme náhled na skutečný výsledný XML kód, který vznikne z table2.
26
<table2 header1="Hodnota" header2="Popis">
První hodnota
Popisek první hodnoty.
Druhá hodnota
Popisek druhé hodnoty.
</table2>
<docsys:table><//>
<docsys:tr style="table-header"><//>
<docsys:td>Hodnota</docsys:td>
<docsys:td>Popis</docsys:td>
</docsys:tr><//>
<docsys:tr><//>
<docsys:td>První hodnota</docsys:td>
<docsys:td>Popisek první hodnoty.</docsys:td>
</docsys:tr><//>
<docsys:tr><//>
<docsys:td>Druhá hodnota</docsys:td>
<docsys:td>Popisek druhé hodnoty.</docsys:td>
</docsys:tr>
</docsys:table>
5.3.2 Seznamy
Syntaxe:
<desclist [style="(styl seznamu)"]>
[<li [caption="(popisek položky)"]>[(obsah položky)]</li> ...]
</desclist>
Jednoduché seznamy tvořené pomocí tagů item a itemstop se překládají na tag desclist,
položky představované paragrafy se přeloží do tagu li, atribut caption je zkopírován. Oproti
layoutové verzi lze navíc zadat styl seznamu:
auto
val-list
Automatický styl (implicitní).
Seznam hodnot nebo parametrů s popiskem, automatický styl pro sekce
parameters a returns.
link-list
Seznam odkazů, automatický styl pro sekci references.
tabled-list Tabulka, implicitní styl, automatický pro všechny ostatní sekce nezmíněné
v tomto seznamu.
chapter-list Seznam kapitol, automatický styl pro generovanou sekci $chapters.
Syntaxe:
<fmtlist [style="(jméno stylu)"]>
[<li>[(obsah položky)]</li> ...]
</fmtlist>
Pokročilejší seznamy tvořené tagem list se překládají na tag fmtlist, položky představované
paragrafy se přeloží do tagu li, atribut style je zkopírován.
27
5.4 Přehled tagů
Tento oddíl shrnuje přehled všech standardních tagů, které byly rozebrány v této kapitole.
V přehledu nejsou speciální tagy </> a <//>.
b
br
code
date
desclist
fmtlist
i
id
img
item
itemstop
kw
link
list
obj
para
spec
sym
table
tablen
table(N)
time
u
url
val
ximg
xlink
28
Tučné písmo.
Zalomení řádku.
Ukázka zdrojového textu.
Datum vytvoření dokumentace.
Obecný jednoduchý seznam.
Formátovaný seznam.
Kurzíva.
Text je zvýrazněn jako identifikátor.
Vloží obrázek či odkaz na něj.
Vytvoří položku „paragrafového“ seznamu.
Ukončí „paragrafový“ seznam.
Text je klíčové slovo.
Odkaz na položku dokumentačního stromu (dokumentovanou entitu).
Obyčejný seznam.
Analogie link, která však může odkazovat i na neexistující cíl.
Blok textu považovaný za odstavec layoutu.
Obsahuje speciální symbol (např. rozšířené nestandardní klíčové slovo).
Zvýrazní text jako symbol.
Obecná tabulka.
Tabulka se zadaným počtem pevných sloupců.
Skupina tagů (N = 1..5) pro tabulky s pevným počtem sloupců.
Čas vytvoření dokumentace.
Podtržení textu.
Vloží odkaz na webovou stránku.
Text je hodnota.
Vloží obrázek z ximg-repository.
Odkaz na soubor z xlink-repository.
29
6. Standardní makra
K dispozici je sada standardních maker, která jsou uvedena v následujícím výčtu společně
s hodnotami, na něž se expandují.
@{at}
@{b "(text)"}
@{begintable "(záhlaví
1)" ...}
@{begintable(N)
"(záhlaví 1)" ...}
@{br}
@{date}
@{empty}
@{endtable "(počet
sloupců)"}
@{endtable(N)}
@{extlink "(odkaz)"}
@{extlink "(jazyk)"
"(odkaz)"}
@{extobj "(odkaz)"}
30
@
<docsys:b>(text)</docsys:b>
<docsys:table(počet argumentů makra)
header1="(záhlaví 1)" ...>
<docsys:table(N) header1="(záhlaví 1)" ...>
<docsys:br /><//>
<docsys:date />
</docsys:table(počet sloupců)>
</docsys:table(N)>
<docsys:link
target="(odkaz)">(odkaz)</docsys:link>
<docsys:link lang="(jazyk)"
target="(odkaz)">[(jazyk)](odkaz)</docsys:link>
<docsys:obj
target="(odkaz)">(odkaz)</docsys:obj>
@{extobj "(jazyk)"
"(odkaz)"}
@{i "(text)"}
@{id "(text)"}
@{img "(odkaz)"}
@{item ["(text)"]}
@{itemstop}
@{kw "(text)"}
@{link [["(jazyk)"]
"(entita)"]}
@{obj [["(jazyk)"]
"(entita)"]}
@{param "(text)"}
@{paramstop}
@{return "(text)"}
@{sp}
@{spec "(text)"}
@{sym "(text)"}
@{throws "(text)"}
@{throwstop}
@{time}
@{u "(text)"}
@{url "(odkaz)"}
@{url "(odkaz)"
"(text)"}
@{val "(text)"}
@{ximg "(odkaz)"}
@{xlink "(odkaz)"}
@{xlink "(odkaz)"
"(text)"}
@{tt "(text)"}
<docsys:obj lang="(jazyk)"
target="(odkaz)">[(jazyk)](odkaz)</docsys:obj>
<docsys:i>(text)</docsys:i>
<docsys:id>(text)</docsys:id>
<docsys:img target="(odkaz)" />
<docsys:item [caption="(text)"] />
<docsys:itemstop />
<docsys:kw>(text)</docsys:kw>
<docsys:link [[lang="(jazyk)"]
[target="(entita)"] />
<docsys:obj [[lang="(jazyk)"]
[target="(entita)"]/>
<docsys:item caption="(text)" />
<docsys:itemstop />
 
<docsys:spec>(text)</docsys:spec>
<docsys:sym>(text)</docsys:sym>
<docsys:itemstop />
<docsys:time />
<docsys:u>(text)</docsys:u>
<docsys:url
target="(odkaz)">(odkaz)</docsys:url>
<docsys:url
target="(odkaz)">(text)</docsys:url>
<docsys:val>(text)</docsys:val>
<docsys:ximg target="(odkaz)" />
<docsys:xlink
target="(odkaz)">(odkaz)</docsys:xlink>
<docsys:xlink
target="(odkaz)">(text)</docsys:xlink>
<docsys:tt>#1</docsys:tt>
Makra @{begintable} a @{endtable} a jejich varianty jsou definovány jen pro standardně
podporované šířky tabulek (tedy 1–5 sloupců). Makra @{extlink} a @{extobj} mohou volitelně
jazyk zakomponovat do odkazu jiným způsobem (zde byly zvoleny hranaté závorky – ty lze chápat
jako metasymbol i jako konkrétní znak navržený pro oddělení jazyka od zbytku textu odkazu).
31
7. Standardní a
automaticky
generované sekce
Pro obvyklé potřeby dokumentace je předdefinováno několik standardních sekcí. Uživatel
může použít i jiné než tyto standardní, ale pak k nim bude zřejmě muset doplnit i způsob jejich
začlenění do výsledné dokumentace – standardní sekce mají všechny náležitosti už hotové a mohou
být rovnou používány. Standardní sekce jsou uvedeny v následujícím výčtu včetně jejich
zamýšleného obsahu.
author
bugs
description
examples
exceptions
history
32
Autor.
Seznam známých chyb
Podrobnější popis entity a jejího fungování.
Oddíl věnovaný příkladům.
Výjimky související s danou entitou.
Historie vývoje a zejména změn dané entity.
implementation
parameters
references
returns
todo
Popis implementace a implementačních specifik.
Parametry entity; tedy zejména parametry funkcí, procedur a
parametrizovatelných typů.
Seznam explicitně zadaných důležitých odkazů svázaných s entitou.
Návratová hodnota funkce.
Seznam věcí, které čekají na vyřízení či dokončení.
Výsadní postavení má anonymní sekce, která slouží jako obšírnější popisek (např.
v seznamech odkazů na hierarchicky podřízené entity). Ve výsledné dokumentaci by její text měl
být umístěn pod záhlavím stránky.
Systém DocSys interně generuje další sekce. Protože tyto automaticky generované sekce
jsou vytvořeny jen interně, zdrojový kód těchto sekcí není k dispozici a uživatel nemůže do něj
přímo zasahovat. Aby nedošlo ke konfliktu se jmény sekcí, které smí uživatel vytvořit, začínají
jejich jména znakem $ (dolar), který není v syntaxi dokumentačního jazyka ve jméně sekce
povolen. Vytváření nestandardních sekcí uživatelem tedy nenese riziko záměny s některou
automaticky generovanou sekcí.
Definovány jsou nyní čtyři automaticky generované sekce: $chapters, $declaration,
$inheritance a $members. Sekce $inheritance obsahuje údaje o dědičnosti entity (např. seznam
předků třídy).
Obsah sekce $declaration tvoří deklarace entity (převzatá ze zdrojového textu). Sekce
$members obsahuje seznam entit, které v hierarchii ve zdrojovém textu, jsou přímými potomky
dané entity (např. datové položky struktur, metody třídy apod.). Každá položka je tvořena odkazem
doplněným o stručnou charakteristiku převzatou z anonymní sekce cíle odkazu. Odkazy v sekci
$members udržují ve výsledné dokumentaci pohromadě hierarchickou strukturu entit.
Sekce $chapters je podobná sekci $members, narozdíl od ní však obsahuje výčet
podřízených entit, které nejsou entitami ve zdrojovém textu. Takové entity mohou vzniknout při
použití explicitní vazby, jak ukazuje následující příklad.
Příklad:
Předpokládejme stále platnost úvodní ukázky s funkcí strcpy(). Nechť se vyskytne ve zdrojovém
textu následující dokumentační komentář.
/** "::strcpy()::SecurityDetails"
display="Více o bezpečnosti funkce strcpy()"
@description
Funkce @{obj "strcpy()"} může být nebezpečná, pokud není zajištěna
dostatečná velikost cílového bufferu. Příliš malý buffer může vést k tzv.
buffer overrun, přepsání paměti mimo buffer, což je vážná chyba, která
může způsobit nejen pád aplikace, ale i její nepředvídatelné další
chování. To lze využít k útokům na privilegované aplikace a donutit je
vykonat libovolný kód pod uživatelským účtem, pod kterým aplikace běží.
Doporučeno je proto vyhýbat se funkci @{id "strcpy()"} a raději místo ní
používat funkci @{obj "strncpy()"}, která umožňuje omezit velikost
kopírovaného bloku.
*/
33
V tomto příkladu je dokumentační blok, který se váže na neexistující entitu pojmenovanou
SecurityDetails. To není chyba! Při zpracování zdrojových textů nemůže systém DocSys mít přehled
o všech entitách, dokud celé zpracování nedokončí. Dokumentační strom je tedy vytvářen i podle
takto explicitně vázaných komentářů. To dovoluje tvořit stránky dokumentace, které se nevážou ke
konkrétní entitě. Takovéto stránky – bez příslušné entity ve zdrojovém textu – nemají pochopitelně
vygenerované sekce $declaration, $inheritance ani $members, ale mohou mít vygenerovanou sekci
$chapters a samy jsou uváděny v sekci $chapters svého rodiče. Jednoduše řečeno, sekce $chapters
je analogická k sekci $members, jen uzly dokumentačního stromu v ní odkazované nepředstavují
regulérní entity ve zdrojovém textu. Tedy následně v tomto konkrétním příkladě bude na stránce
věnované funkci strcpy() vytvořen seznam podkapitol daného tématu a v něm odkaz Více o
bezpečnosti funkce strcpy(), který povede právě na stránku vygenerovanou z komentáře zde
uvedeného.
34
35
8. Titulní stránka
Z dokumentačních komentářů se vygeneruje dokumentace k entitám a řada dalších
informací (např. abecední seznamy entit). Výsledná dokumentace však potřebuje dodat také titulní
stránku. Titulní stránka se zapisuje také pomocí prostředků dokumentačního jazyka. Zdrojový text
titulní stránky je uložen v samostatném souboru; jeho obsahem je pouze text v dokumentačním
jazyce, nejsou tu již žádné komentáře.
Při psaní titulní stránky platí některá specifika. Zejména je nutné mít v patrnosti, že nenáleží
žádnému jazykovému kontextu, tedy používání tagů link a obj je omezeno – vždy musí být použita
plně kvalifikovaná cesta k entitě včetně jazyka. Dále by měl být vždy specifikován metaatribut
display, jehož hodnota se stává titulkem celé dokumentace. V zápise titulní stránky by měly být
použity pouze následující sekce.
header
description
footer
36
Záhlaví stránky obsahující nadpis, logo atd.
Vlastní text titulní stránky, popis produktu a dokumentace.
Zápatí stránky obsahující např. datum vzniku dokumentace, verzi produktu
apod.
Příklad:
Zdrojový soubor jednoduché titulní stránky může vypadat např. takto:
display="Moje jednoduchá aplikace 1.0"
@header
Moje jednoduchá aplikace 1.0@{br}
vývojová dokumentace
@description
Moje jednoduchá aplikace nedělá vůbec nic. Dokonce méně
než Hello, world! Je napsaná v jazyce C++, popis použitých
rutin a typů najdete <link lang="C++" target="::">pod tímto
odkazem</link>.
@footer
Moje jednoduchá aplikace © Moje společnost 2004,
@{url "http://www.mojespolecnost.cz"}.
Dokumentace byla vygenerovaná <date />, <time /> systémem DocSys.
37
9. Vygenerované
XML dokumenty
Tato kapitola se věnuje vygenerovaným XML dokumentům, jejich struktuře a vzniku. Je
určena zejména pro uživatele, kteří chtějí tvořit balíky pro další zpracování vygenerovaných XML
dokumentů (např. pro jejich konverzi do jiných formátů). Běžný uživatel systému DocSys může
tuto kapitolu přeskočit.
Průběh zpracování zdrojového textu dokumentace si lze představit ve třech fázích:
1. Nejprve je zdrojový text načten, během čehož jsou expandována makra, a je
zkontrolována syntaktická správnost (jde zejména o korektní párování tagů v rámci
sekcí).
2. Vytvoří se prototyp XML dokumentu (nazývaný primární XML dokument), ve kterém už
jsou layout, sekce i zmíněné speciální tagy nahrazeny regulérními prostředky jazyka
XML. Layout je přeměnen v tagy para, jak bylo popsáno dříve, transformace sekcí a
speciálních tagů bude popsána v dalším textu. V této fázi vznikne tedy řádný XML
dokument, v němž jsou si všechny tagy rovny a žádné speciality vybočující z jazyka
XML již nejsou přítomné.
38
3. Primární XML dokument není příliš dobře strukturovaný, jak lze nahlédnout ze způsobu
jeho vzniku (mnoho rozmanitých tagů, příliš mnoho rolí tagu para atd.); proto se následně
zpracuje XSL šablonou (tzv. primární XSL šablonou), která tyto nedostatky napraví. Tato
šablona vlastně plní roli "standardní knihovny", neboť se stará o to, aby standardní tagy
ve výsledném XML dokumentu dostaly konečný tvar odpovídající jejich zamýšlenému
významu a použití.
Kromě XML dokumentů, které obsahují zpracovaný obsah dokumentačních komentářů, je
vygenerováno ještě množství indexů (rejstříků). Jejich struktura bude také popsána, protože stejně
jako u dokumentů vzniklých přímo z dokumentačních komentářů, i indexy jsou předmětem dalšího
zpracování.
Všechny vytvořené XML dokumenty jsou generovány podle podobného vzoru, mají
shodnou kostru; jsou organizovány v pevné adresářové struktuře, což usnadňuje jejich zpracování a
orientaci v ní. Organizace souborů v adresářové struktuře i jejich společná kostra bude popsána
v následujících dvou oddílech.
9.1 Organizace souborů
Protože vygenerovaných dokumentů je mnoho a je potřeba je provázat odkazy, je podstatná
organizace výsledných souborů v souborovém systému; díky pevně dané organizaci mohou být
odkazy mezi soubory relativní, a je tedy možné celý adresář s výslednými XML dokumenty i
případnými dalšími externími soubory (v ximg- a xlink-repository) libovolně kopírovat při
zachování funkčnosti odkazů. Struktura, do níž se ukládají XML dokumenty, je následující.
(výstupní adresář)/
Tento adresář zadá uživatel v konfiguraci programu, který dokumenty generuje. Zpravidla
tento adresář bude ve stejném adresáři jako konfigurační soubor a bude pojmenován XML.
(výstupní adresář)/index/
Adresář s globálními daty, zejména s indexy. Struktura indexů (globálních i lokálních) je
vygenerována vždy, nezávisle na zákazu generování indexů v konfiguraci programu; v případě
zákazu však tyto soubory nemají žádný faktický obsah – vytvořena je v nich jen příslušná struktura
XML značek, v níž chybí data. Díky tomu nemusí aplikace, která zpracovává tyto XML
dokumenty, rozlišovat případy existujících a neexistujících souborů.
(výstupní adresář)/index/index.xml
Titulní stránka dokumentace.
(výstupní adresář)/index/index.lang.xml
Tento soubor má platný obsah vždy; obsahuje seznam jazyků, k nimž byla dokumentace
generována – je to tzv. jazykový index. Fakticky se jedná o seznam generovaných podadresářů
výstupního adresáře (bez podadresáře index/).
39
(výstupní adresář)/index/(sestava indexů)
Sestava indexů je tvořena sadou několika dokumentů. První část sady se sestává ze souborů
pojmenovaných index.(písmeno).xml, kde (písmeno) je ASCII znak velké anglické abecedy
(vygenerovány jsou vždy soubory pro všechna písmena A – Z); tyto soubory obsahují index stránek
se jmény začínajícími znakem (písmeno) (bráno case-insensitive). K této sadě indexů náleží ještě
soubor index.specials.xml, do kterého jsou umístěny ostatní položky. Dokumenty z této první
skupiny se nazývají indexy pro znak. Soubor index.all.xml obsahuje sloučení všech souborů
index.(písmeno).xml i souboru index.specials.xml – tento dokument se nazývá celkový index.
Soubor index.list.xml obsahuje seznam souborů index.(písmeno).xml a index.specials.xml, které
obsahují nějaká relevantní data – slouží tedy jako index použitých znaků.
V tomto adresáři je umístěna sestava globálních indexů. Globální indexy jsou indexy
vytvořené ze všech jazykových kontextů, u nichž je povoleno zařazení jejich obsahu do globálního
indexu (může být v jejich konfiguraci zakázáno).
(výstupní adresář)/(jazyk)/
Každý jazyk (resp. jazykový kontext) má vlastní adresář, v němž jsou umístěny všechny
soubory, které byly vygenerovány z jeho jazykového kontextu.
(výstupní adresář)/(jazyk)/index.tree.xml
Hierarchický index (stromový rejstřík) jazykového kontextu daného jazyka kopíruje
hierarchickou strukturu dokumentovaných entit.
(výstupní adresář)/(jazyk)/(sestava indexů)
Sestava indexů tvarem shodná s (výstupní adresář)/index/(sestava indexů), položky pro
indexy jsou však brány pouze z jazykového kontextu daného jazyka.
(výstupní adresář)/(jazyk)/(uzlová struktura)
Uzlová struktura je souhrn dokumentů vygenerovaných z dokumentačních bloků
jednotlivých uzlů v jazykovém kontextu daného jazyka – tedy stránek dokumentace. Stránka kořene
hierarchie jazykového kontextu se vždy nachází v souboru node.root.xml. Ostatní uzly mají
dokumentaci v souborech pojmenovaných node.(identifikátor).xml, kde (identifikátor) je libovolný
řetězec zvolený tak, aby jméno souboru (bez přípony) bylo unikátní mezi všemi vygenerovanými
soubory z celého adresářového stromu (výstupní adresář)/.
Za povšimnutí stojí fakt, že všechny generované XML dokumenty se nacházejí v adresářové
hloubce dva, lze tedy automaticky snadno generovat odkazy na pevné body této struktury, což jsou
části indexů, kořeny generovaných hierarchií dokumentů i další soubory: ximg-repository či xlinkrepository je vhodné umístit do adresáře na stejné úrovni, na které se nachází výstupní adresář, a
nastavit cestu k nim relativně vzhledem ke generovaným dokumentům (např. ximg-repository může
být cesta ../../images/).
40
9.2 Kostra dokumentů
Předchozí oddíl popsal adresářovou strukturu, do které se generují výsledné XML
dokumenty; zmíněno tam bylo několik druhů dokumentů (uzly dokumentačního stromu, titulní
stránka, indexy několika typů) – ty se navzájem liší svým obsahem, dokumenty obsahující stejný
druh obsahu mají jméno tvořené podle stejného vzoru (např. všechny dokumenty k uzlů
dokumentačního stromu jsou pojmenovány node.*.xml).
Ač tedy je několik druhů dokumentů s různým obsahem, všechny tyto dokumenty mají
společnou kostru, společné zásady, kterými se řídí jejich struktura. Obecně struktura všech
generovaných dokumentů se řídí tímto vzorem:♣
<(kořenový element + jeho atributy)>
<docsys:properties>
<docsys:system-properties>
[<docsys:property name="(jméno property)" value="(hodnota
property)" /> ...]
</docsys:system-properties>
<docsys:custom-properties>
[<docsys:property name="(jméno property)" value="(hodnota
property)" /> ...]
</docsys:custom-properties>
</docsys:properties>
<docsys:content>
(vlastní obsah dokumentu)
</docsys:content>
</(kořenový element)>
Kořenový element je různý podle typu obsahu dokumentu (např. dokumenty k uzlům mají
jiný kořenový tag než indexy). Atributy kořenového elementu jsou zejména deklarace XML
namespaces. Vlastní obsah dokumentu už je specifickou záležitostí pro daný typ dokumentu, daný
kořenovým elementem (a naznačený i pojmenováním souboru, v němž je dokument uložen –
závazný je ovšem kořenový element).
Obsahem tagu docsys:properties jsou tzv. properties dokumentu – pojmenované jednoduché
textové hodnoty, které může používat aplikace, která dokument následně zpracovává. Jedna
property je reprezentovaná tagem docsys:property. Properties jsou dvou druhů: systémové
properties (uzavřené do tagu docsys:system-properties) jsou údaje vložené modulem, který soubor
vygeneroval, uživatelské (uzavřené do tagu docsys:custom-properties) jsou zadané přímo
uživatelem.
Systémové properties jsou definovány tyto:
creation-date
creation-time
global-index
docsys-generator
language-index
Datum vytvoření dokumentace.
Čas vytvoření dokumentace.
Příznak, zda existuje globální index.
Informace o generátoru, který stránku vygeneroval.
Příznak, zda existuje lokální index.
♣
Ukázky XML dokumentů jsou hierarchicky zformátovány podle zanoření významných tagů a příliš dlouhé řádky jsou
zalomeny a odsazeny. Tyto úpravy ovšem nejsou korektní z hlediska obsahu XML, protože konec řádku či bílé znaky
navíc v obsahu tagu ovlivňují obsah dokumentu, a jsou činěny pouze za účelem zvýšení přehlednosti ukázky.
41
node-parent-id
node-parent-name
node-parent-display
node-name
node-display
this-id
this-language-id
this-language-name
tree-index
Identifikátor souboru rodičovského uzlu.
Jméno rodičovského uzlu.
Popisek rodičovského uzlu.
Jméno tohoto uzlu.
Popisek tohoto uzlu.
Identifikátor tohoto souboru.
Identifikátor jazyka tohoto uzlu.
Jméno jazyka tohoto uzlu.
Příznak, zda existuje stromový index pro daný jazyk.
Ne všechny tyto properties mají význam pro všechny typy dokumentů, a proto se
v některých typech dokumentů některé properties nevyskytují vůbec (např. properties se jménem
začínajícím node se vyskytují jen v dokumentech generovaných k uzlům dokumentačního stromu).
Properties označené v tomto výčtu jako příznaky, nabývají pouze hodnot yes a no, properties
označené jako identifikátor (jejich jméno končí na id) obsahují relativní cestu (od aktuálního
dokumentu) k jinému dokumentu – v cestě však není specifikována přípona cílového souboru, což
dovoluje snadnou konverzi do různých hypertextových formátů, jako je např. HTML, při které je
jméno doplněno o příslušnou příponu.
Uživatelské properties zadává uživatel a mohou zásadně ovlivnit zpracování dokumentu –
záleží na aplikaci, která dokument následně zpracovává. Standardní uživatelské properties jsou dvě:
xlink-repository Část adresy, která se má předsadit cílům tagu xlink.
ximg-repository
Analogie xlink-repository pro tag ximg.
Příklad:
Následuje příklad typického obsahu properties dokumentu.
42
<docsys:properties>
<docsys:system-properties>
<docsys:property name="docsys-generator"
value="Original DocSys XML Generator 1.0" />
<docsys:property name="creation-date" value="27/09/2004" />
<docsys:property name="creation-time" value="11:16:44" />
<docsys:property name="this-language-name" value="DocSys" />
<docsys:property name="this-language-id" value="DocSys" />
<docsys:property name="language-index" value="yes" />
<docsys:property name="tree-index" value="yes" />
<docsys:property name="global-index" value="yes" />
<docsys:property name="this-id" value="node.01F32AC0" />
<docsys:property name="node-name" value="sources" />
<docsys:property name="node-display" value="sources" />
<docsys:property name="node-parent-id" value="node.01B1FBD0" />
<docsys:property name="node-parent-name" value="MyApp" />
<docsys:property name="node-parent-display"
value="Moje aplikace 1.0" />
</docsys:system-properties>
<docsys:custom-properties>
<docsys:property name="xlink-repository" value="../../files/" />
<docsys:property name="ximg-repository" value="../../img/" />
</docsys:custom-properties>
9.3 Indexy
Indexů (rejstříků) je několik druhů: hierarchický (stromový) index, index pro znak, index
použitých znaků (znakový index), jazykový index a celkový index. Všechny druhy indexů mají
strukturu odvozenou od základní kostry vygenerovaných dokumentů.
Hierarchický index používá dva speciální tagy: docsys:tree-index jako kořenový tag a
docsys:tree-item pro položku hierachické struktury v obsahu tagu docsys:content; hierarchická
struktura je modelována hierarchií tagů.
Příklad:
Následuje ukázka hierarchického indexu (s vynecháním properties a konstrukce <?xml ...>, kterou
by měl XML dokument začínat). V ukázce je vidět i deklarování XML namespaces pomocí
konstrukce xmlns.
<docsys:tree-index xmlns:docsys="DocSys XML NS" xmlns:nondocsys="Non-DocSys
XML NS">
<docsys:properties>
...
<docsys:content>
<docsys:tree-item target-id="node.root" caption="Obecná dokumentace">
<docsys:tree-item target-id="node.01E69670"
caption="Hlavičkové soubory" />
</docsys:tree-item>
</docsys:content>
</docsys:tree-index>
43
Atribut target-id tagu docsys:tree-item udává (nejen v tomto případě, ale ve všech ostatních
typech dokumentů a tagů) identifikátor souboru, který je odkazován. Atribut caption je popisek
odkazu.
Jednoduchým indexem je jazykový index; ten se používá jen na globální úrovni. Obsahuje
seznam jazykových kontextů. Použivá dva speciální tagy docsys:lang-index a docsys:index-item.
Příklad:
Ukázka opět zachycuje fragment dokumentu redukovaný o properties.
<docsys:lang-index xmlns:docsys="DocSys XML NS" xmlns:nondocsys="Non-DocSys
XML NS">
<docsys:properties>
...
<docsys:content>
<docsys:index-item lang-id="C++" lang-name="C++" />
<docsys:index-item lang-id="DocSys" lang-name="DocSys" />
</docsys:content>
</docsys:lang-index>
Atribut lang-id udává identifikátor jazykového kontextu, který se shoduje se jménem
adresáře, jenž obsahuje dokumentaci z daného jazykového kontextu. Atribut lang-name pak
obsahuje jméno jazyka, které má být používáno pro interakci s uživatelem.
Index pro znak obsahuje seznam entit, jejichž jméno daným znakem začíná. Použity jsou
jen znaky anglické abecedy, pro ostatní znaky je vyhrazen jeden speciální dokument. Index pro
znak používá tři speciální tagy: docsys:char-index, docsys:index-group a docsys:index-item.
Příklad:
V ukázce je vynechán opět blok properties.
<docsys:char-index xmlns:docsys="DocSys XML NS" xmlns:nondocsys="Non-DocSys
XML NS" char="A">
<docsys:properties>
...
<docsys:content>
<docsys:index-group caption="A">
<docsys:index-item target-id="node.01D94420" target-name="A" />
<docsys:index-item target-id="node.01D8F348" target-name="X/A" />
</docsys:index-group>
<docsys:index-item target-id="node.01DDBEB0" caption="A.1"
target-name="X/A/A.1" />
<docsys:index-item target-id="node.01D8F850" caption="A.1.1"
target-name="X/A/A.1/A.1.1" />
</docsys:content>
</docsys:char-index>
44
Kořenovým tagem je tedy docsys:char-index, který má nepovinný atribut char – znak,
kterým začínají jména v tomto indexu. Pokud tento atribut chybí, jedná se právě o onen speciální
dokument, kde jsou všechna ostatní jména. Tag docsys:index-group se vyskytuje zřídka a obsahuje
položky rejstříku, které mají stejné jméno, a je tedy nutné je odlišit ještě jinak – třeba užít pro popis
atribut target-name, který je jinak celým jménem entity použitým pro odkazy v rámci
dokumentačního stromu. Tag docsys:index-item je jinak vlastní položka indexu, a pokud tomu
nebrání konflikt jmen v indexu, neuzavírá se do jiného tagu. Atribut caption je vždy popisek, vlastní
jméno, které by měl vidět uživatel, atribut target-id má stejný význam jako v předchozích
případech.
Všechny tyto dílčí indexy jsou spojeny ještě v celkový index. Ten obsahuje stejnou sadu
tagů, až na tag docsys:index, jako indexy pro jednotlivé znaky.
Příklad:
Ukázka je zkrácena opět o properties a také o intuitivně zřejmou část dat.
<docsys:index xmlns:docsys="DocSys XML NS" xmlns:nondocsys="Non-DocSys XML
NS">
<docsys:properties>
...
<docsys:content>
<docsys:char-index char="A" />
<docsys:char-index char="B" />
...
<docsys:char-index char="H">
<docsys:index-item target-id="node.01E69670"
caption="Hlavičkové soubory" target-name="headers" />
</docsys:char-index>
<docsys:char-index char="I" />
...
<docsys:char-index />
</docsys:content>
</docsys:index>
Tag docsys:index je kořenovým tagem dokumentu, obsah je tvořen seznamem skupin znaků
(tedy vlastně dílčích indexů), jejichž tělo je shodné s tělem jejich tagu docsys:content. Pokud chybí
u skupiny představované tagem docsys:char-index atribut char, jedná se opět o skupinu jmen, která
nezačínají na žádné z předchozích uvedených znaků.
Znakový index udržuje přehled o tom, které z vygenerovaných indexů pro znak jsou
skutečně platné (naplněné nějakými daty). Díky tomuto indexu je možné vygenerovat seznam
znaků provázaných s příslušnými indexy, aniž by bylo nutné tyto indexy nějak zkoumat.
Kořenovým tagem těchto znakových indexů je docsys:index-list, pro položky uzavřené v tagu
docsys:content je použit opět tag docsys:index-item.
45
Příklad:
Zobrazen je krátký index pouze se dvěma položkami; opět je vynechán blok properties.
<docsys:index-list xmlns:docsys="DocSys XML NS" xmlns:nondocsys="Non-DocSys
XML NS">
<docsys:properties>
...
<docsys:content>
<docsys:index-item target-id="index.G" char="G" />
<docsys:index-item target-id="index.H" char="H" />
</docsys:content>
</docsys:index-list>
9.4 Dokumentace entit
Dokumentační komentář (tedy komentář svázaný s nějakou entitou) je transformován
nakonec do jednoho XML souboru – přemění se v dokumentační stránku. Struktura tohoto XML
souboru je opět odvozena od základní kostry popsané dříve. Novými speciálními tagy tu jsou
docsys:node (kořenový element), docsys:brief (vyhrazený pro obsah anonymní sekce),
docsys:documentation a docsys:section. Celý dokument má tuto strukturu:
<docsys:node xmlns:docsys="DocSys XML NS" xmlns:nondocsys="Non-DocSys XML NS">
<docsys:properties>
...
<docsys:content>
<docsys:brief>
...
</docsys:brief>
<docsys:documentation>
<docsys:section name="(jméno sekce)">
...
</docsys:section>
...
</docsys:documentation>
</docsys:content>
</docsys:node>
Obsah každé sekce, s výjimkou anonymní, je uzavřen do tagu docsys:section, jehož atribut
name obsahuje jméno sekce; obsah anonymní sekce, jak bylo řečeno, je uzavřen v tagu docsys:brief
(zde je též patrné její výsadní postavení). Kromě sekcí zapsaných uživatelem se v XML dokumentu
objeví též automaticky generované sekce.
U automaticky generovaných sekcí jsou zajímavé sekce $members a $declaration; ostatní
generované sekce jsou vytvořeny pomocí standardních tagů, tyto dvě jmenované sekce však mají
specifickou strukturu.
Sekce $members používá speciální tagy docsys:member-group, docsys:member,
docsys:linktext a docsys:desc. Pro názornost před jejich popisem bude uveden krátký příklad.
46
Příklad:
V ukázce je pouze sekce $members, jak bude vypadat ve výsledném XML dokumentu; zbytek
dokumentu (povinné tagy včetně kořenového tagu docsys:node i properties jsou z příkladu
odstraněny).
...
<docsys:section name="$members">
<docsys:member-group type="public-methods">
<docsys:member>
<docsys:linktext>
<docsys:link target-id="node.01FE9670">Method()</docsys:link>
</docsys:linktext>
<docsys:desc>
Tato funkce je členskou funkcí jedné nejmenované třídy.
</docsys:desc>
</docsys:member>
<docsys:member>
<docsys:linktext>
<docsys:link target-id="node.01FC9680">
AnotherMethod()
</docsys:link>
</docsys:linktext>
<docsys:desc>
Tato funkce je další členskou funkcí jisté nejmenované třídy.
</docsys:desc>
</docsys:member>
</docsys:member-group>
<docsys:member-group type="public-variables">
<docsys:member>
<docsys:linktext>
<docsys:kw>int</docsys:kw> <docsys:link
target-id="node.01ADE680">A</docsys:link>
</docsys:linktext>
<docsys:desc>
Veřejná proměnná... opět od jedné nejmenované třídy.
</docsys:desc>
</docsys:member>
</docsys:member-group>
</docsys:section>
...
Tag docsys:member-group představuje skupinu potomků v hierarchii entit, kteří jsou
stejného typu – jaké jsou přípustné typy, je záležitost konkrétního jazyka a jeho následného
zpracování; typ potomků v dané skupině je vyjádřen atributem type. Obsahem tagu docsys:membergroup je sekvence tagů docsys:member, které představují položky výčtu. Každá položka se sestává
z textu, který má funkci odkazu, zabaleného v tagu docsys:linktext (text může obsahovat víc než
samotný odkaz, jak je vidět u položky pro veřejnou proměnnou A) a z popisu položky, který je
tvořen obsahem anonymní sekce odkazované entity.
47
Sekce $declaration používá speciální tag docsys:declaration; její obsah je tvořen sekvencí
těchto tagů, které obsahují jednotlivé deklarace entity – entita totiž může mít víc deklarací, např.
funkce přetížené počty či typy argumentů (overloaded functions v C++). Vlastní deklarace (obsahy
tagu docsys:declaration) pak už jsou tvořeny pomocí běžných uživatelsky přístupných tagů.
Příklad:
V ukázce je pouze sekce $declaration, jak bude vypadat ve výsledném XML dokumentu; zbytek
dokumentu (povinné tagy včetně kořenového tagu docsys:node i properties jsou z příkladu
odstraněny).
...
<docsys:section name="$declaration">
<docsys:declaration>
<kw>int</kw> <id>funkce</id><sym>(</sym><obj
target="A">A</obj><sym>&</sym> <id>parametr</id><sym>);</sym>
</docsys:declaration>
<docsys:declaration>
<kw>int</kw> <id>funkce</id><sym>(</sym><kw>int</kw>
<id>parametr</id><sym>);</sym>
</docsys:declaration>
</docsys:section>
...
9.5 Titulní stránka
Titulní stránka je svou strukturou téměř shodná s dokumentací entity, která byla popsána
v minulém oddílu. Rozdíl je jen v tom, že kořenovým tagem je docsys:startpage místo docsys:node
a tag docsys:content obsahuje přímo seznam sekcí (tagů docsys:section).
Příklad:
Ukázka obsahuje kostru titulní stránky.
<docsys:startpagexmlns:docsys="DocSys XML NS" xmlns:nondocsys="Non-DocSys XML
NS">
<docsys:properties>
...
<docsys:content>
<docsys:section name="(jméno sekce)">
...
</docsys:section>
...
</docsys:content>
</docsys:startpage>
48
49
10. Jazykový
kontext DocSys
Při vytváření dokumentace je občas nutné popsat nějaké entity, které nespadají do žádného
jazyka – např. adresářovou strukturu a soubory dokumentovaného projektu, popis jeho architektury
atd. Takový popis je též potřeba zahrnout mezi generované stránky dokumentace a provázat ho
s nimi. Speciálně pro vložení takových dokumentů slouží jazykový kontext pojmenovaný DocSys –
stránky s dokumentací, která stojí mimo vlastní zdrojový kód projektu, pak mohou být umístěny
v tomto kontextu a odděleny od dokumentace kódu.
Jazykový kontext DocSys je svázán i s jednoduchým jazykem usnadnění zápisu hierarchicky
strukturovaných kapitol; hierarchizace textu kapitol přirozeně zapadá do filozofie systému DocSys.
Tento jazyk není vůbec nutné používat, ale může trochu usnadnit a zpřehlednit zápis složitější
hierarchie kapitol.
Fungování jazyku DocSys lze přirovnat k fungování adresářové struktury souborového
systému. Entity jazyka DocSys představují „adresáře“, které tvoří přímo stromovou strukturu
jazykového kontextu. Kořen hierarchie se jmenuje / (lomítko) a jako oddělovač hierarchie slouží též
znak / (lomítko). Při zápisu odkazů lze používat i vyhrazené jméno .. (dvě tečky), které odkazuje na
předka hierarchie.
50
Příklad:
Pojmenování /A/B/C v jazyce DocSys odkazuje na entitu C, která je hierarchickým potomkem
entity B, jež je potomkem entity A, která je již potomkem kořenové entity / (kořenu celé hierachie
jazyka DocSys, kořenu jazykového kontextu). Toto jméno je absolutní, protože začíná od kořenu a
nemůže být zaměněno za jiné; jména nezačínající na / jsou relativní vůči místu svého použití –
např. pro entitu /A/B jméno C odkazuje na entitu /A/B/C, v případě entity /A by odkazovalo na
entitu /A/C.
Pokud u entity /A/B/C (např. v jejím dokumentačním komentáři) je užito jméno .., odkazuje se na
entitu /A/B, jméno ../C by odkazovalo zpět na entitu /A/B/C. Je vidět, že analogie s cestami
v souborovém systému je přímočará a přirozená.
Entity jazyka DocSys se deklarují svým jménem uzavřeným do uvozovek (pravidla pro
jejich zápis odpovídají uvozovkovaným řetězcům), deklarace se mohou libovolně opakovat. Za
deklarací může následovat blok deklarací uzavřený ve složených závorkách – relativní jména
deklarací uvnitř tohoto bloku se pak vztahují k deklaraci, kterou blok následoval. Bloky se mohou
vnořovat, relativní jména deklarací stojících mimo jakýkoliv blok se vztahují k entitě / (kořen
hierarchie jazyka DocSys). Celkově tedy fungování entit a bloků jazyka DocSys připomíná
fungování namespaces jazyka C++.
Příklad:
Malá ukázka schopností vnořovat hierarchicky entity jazyka DocSys. Řádky jsou očíslovány a
okomentovány pod ukázkou.
(1)
(2)
(3)
(4)
(5)
(6)
(7)
(8)
(9)
(10)
(11)
(12)
(13)
(14)
"A"
{
"B"
"C"
"C/D"
"E" {
"F"
}
"/G" {
"H"
}
}
Řádek 1 deklaruje entitu A; plným jménem tedy /A – nachází se mimo jakýkoliv blok, tedy její
relativní jméno (nezačíná lomítkem) je relativní vůči kořenu hierarchie (tedy entitě /).
Otevřen blok za entitou /A, všechny relativní odkazy uvnitř tohoto bloku jsou vztaženy k /A. Blok
končí na řádku 14.
Řádky 3 a 4 deklarují entity B a C (plnými jmény /A/B a /A/C); relativní jména jsou vztažena
k bloku, ve kterém se nacházejí.
Řádek 5 deklaruje entitu /A/B/C/D. Je možné užít i takovýchto složených jmen, jména nemusí být
elementární – to je vhodné např. pro takové osamocené deklarace. I kdyby nebylo dřív deklarováno
/A/B/C, nevadilo by to. Pořadí deklarací není důležité, dokonce jsou doplněny i chybějící články
hierarchie, které jsou implikovány deklaracemi.
51
Řádek 7 otevírá blok příslušející entitě /A/E, na řádku 8 pak je deklarováno /A/E/F (opět se
uvažuje vztah relativních jmen v bloku vůči entitě svázané s blokem).
Na řádku 11 je užita praktika, která by se neměla užívat – popírá totiž hierarchii tvořenou bloky.
Deklarována je tu entita /G, absolutní jméno má přednost před vztažením jména v deklaraci ke
jménu bloku. Následně otevřený blok uvnitř sebe deklaruje entitu /G/H.
Dokumentační i obyčejné komentáře jsou shodné s komentáři definovanými pro jazyk C++
(viz též úvodní ukázka). Jednořádkové obyčejné komentáře začínají // (dvojicí lomítek) a končí
koncem řádku; jednoduchý dopředný blok je v komentářích uvozených //> a jednoduchý zpětný
blok v komentářích začínajících /// (trojice lomítek). Víceřádkové komentáře jsou uzavřeny mezi /*
a */ (zanořování není možné). Úplný blok využívá víceřádkových komentářů, kdy otevření
komentáře je rozšířeno o jednu hvězdičku následovanou bílým znakem (toto opatření umožňuje
používat i „ozdobné“ komentáře složené z řad hvězdiček); tedy blok je uzavřen mezi /** a */.
Jazyk DocSys též využívá zjednodušení preprocesoru C/C++; toto zjednodušení dovoluje
pouze definice celočíselných konstant a jejich užívání ve výrazech direktivy pro podmíněný
překlad. Díky tomu lze části této společné dokumentace vypustit definováním vhodné hodnoty
makra. Běžně není však důvod makra ani direktivy používat – pro pokročilé uživatele je uvedena
gramatika dokumentačního jazyka v samostatném oddíle.
52
Příklad:
Tento příklad ukazuje, k čemu se skutečně jazyk DocSys hodí a k čemu má být používán.
"/"
/** <- display="/"
@
Kořenový adresář projektu Moje aplikace 1.0.
@description
Kořenový adresář pro kompilaci pod platformou Win32 musí být
umístěn v adresáři X:\MyApp; pro tento adresář jsou totiž
přednastaveny cesty v konfiguraci překladače.
*/
{
"Makefile"
/** <@
Makefile pro standardní utilitu MAKE.
@description
Tento makefile je kompatibilní se všemi běžnými MAKE a lze
jej použít i na platformě Win32 – ovšem za předpokladu, že
<link target="/">kořenový adresář</link> je umístěn na
očekáváném místě.
Výsledek překladu bude zapsán do adresáře @{link "../build"}.
*/
//> Adresář s veřejnými hlavičkovými soubory.
"include"
{
//> V tomto souboru jsou prototypy všech nestatických funkcí.
"header.h"
}
//> Zdrojové soubory s implementací všech funkcí.
"source"
{
"main.cpp"
/// Funkce main & spol.
"secret.cpp"
/// Interní tajné rutiny.
}
/**
@
Zdrojový soubor resources s informacemi o aplikaci pro
platformu Win32.
*/
"resources/MyApp.rc"
/**
@
Adresář se výsledkem překladu.
}
@description
Dle vybrané platformy bude vytvořen podadresář s výslednými
binárními soubory i mezivýsledky. Příkaz make clean čistí pouze
mezivýsledky pro aktuálně zvolenou platformu, zlikvidovat
všechny mezivýsledky lze příkazem make clean_all.
*/
"build"
53
Dodatky
A. Gramatika jazyka DocSys
Pro pokročilejší uživatele je uvedena plná gramatika jazyka jazykového kontextu DocSys,
která zachycuje i podmíněný překlad částí zdrojového textu. Gramatika se řídí následujícími
konvencemi.
1. Levá a pravá strana pravidel gramatiky jsou odděleny znakem : (dvojtečka). Pravidla
mohou být doplněna komentáři shodnými s komentáři v jazyce C++.
2. V pravidlech kromě preprocessor_directive znamená mezera 0 a více výskytů
whitespace; v pravidle preprocessor_directive znamená mezera 0 a více výskytů
"whitespace bez newline".
3. Pokud je obsah pravidla ohraničen dvojicí podtržítek, význam je intuitivní.
4. Některé řádky jsou označeny vpravo číslem v závorce pro pozdější odkazování
v poznámkách; toto očíslování nemá co dělat s vlastními pravidly gramatiky.
Bílé znaky (whitespace) jsou znaky mezera (space), horizontální tabulátor (tab), vertikální
tabulátor (vtab), zalomení řádku (newline), posun stránky (formfeed) a komentář. Zdrojový soubor
je rozdělen na bílé znaky a terminály gramatiky. Pokud se ve zdrojovém souboru vyskytne něco
jiné, není soubor správný.
54
Terminály:
•
Vyhrazená slova preprocesoru (define, undef, if, elif, else, endif).
•
Lexikální elementy (entity, value, identifier, number).
•
Řetězce použité v pravidlech gramatiky uzavřené mezi dvojici apostrofů (znak ').
Pravidla:
block
:
:
:
:
__prázdný blok__
block preprocessor_directive
block entity
block entity '{' block '}'
preprocessor_directive
:
:
:
:
:
:
:
'#' define identifier newline
'#' define identifier value newline
'#' undef identifier newline
'#' if expression newline block
'#' elif expression newline block
'#' else newline block
'#' endif newline
expression
: logical_or_expression
logical_or_expression
: logical_and_expression
: logical_or_expression '||' logical_and_expression
logical_and_expression
: equality_expression
: logical_and_expression '&&' equality_expression
equality_expression
: relational_expression
: equality_expression '==' relational_expression
: equality_expression '!=' relational_expression
relational_expression
:
:
:
:
:
additive_expression
: unary_expression
: additive_expression '+' unary_expression
: additive_expression '-' unary_expression
unary_expression
: primary_expression
: '-' primary_expression
: '!' primary_expression
primary_expression
: number
: identifier
: '(' logical_or_expression ')'
(1)
(2)
(3)
(4)
(5)
(6)
(7)
additive_expression
relational_expression '<' additive_expression
relational_expression '>' additive_expression
relational_expression '<=' additive_expression
relational_expression '>=' additive_expression
55
// lexikální elementy
identifier
: identifier_begin
: identifier digit
: identifier identifier_begin
identifier_begin
: __[_a-zA-Z]|[^\x00-\xC0]__ // pro zadání použit regulární výraz
value
: digit_sequence
: '-' digit_sequence
number
: digit_sequence
entity
: '"' char_sequence '"'
char_sequence
: char
: char_sequence char
char
: __libovolný znak mimo konce řádku a uvozovek__
: '""'
digit_sequence
: digit
: digit_sequence digit
digit
: __[0-9]__
Poznámky:
•
Direktiva (1) definuje symbol jména určeného obsahem identifier. Symbolu je přiřazena
hodnota 1.
•
Direktiva (2) definuje symbol jména určeného obsahem identifier. Symbolu je přiřazena
hodnota odpovídající dekadickému zápisu celého čísla ve value. Rozsah celého čísla
může být implementací omezen (rozsahem typu int v C/C++ pro danou platformu),
v případě, že se hodnota nachází mimo rozsah definovaný implementací, není chování
definováno.
•
Pokud je direktivami (1) a (2) definován již existující symbol, je mu přiřazena hodnota
podle právě zpracovávané direktivy.
•
Výraz expression v direktivách (4) a (5) je vyhodnocen podle aritmetiky definované
gramatikou. Každý definovaný symbol ve výrazu je nahrazen svou hodnotou, ostatním
identifikátorům je přiřazena hodnota 0. Pokud se hodnota výrazu během vyhodnocování
dostane mimo definovaný rozsah, chování je nedefinováno. Následující blok je
zpracován, pokud je hodnota výrazu nenulová.
B. Schémata XML dokumentů
Součástí dokumentace jsou XML schémata generovaných XML dokumentů. Tato schémata
jsou určena jako pomoc pro tvůrce šablon a nástrojů pro zpracování výstupu ze systému DocSys a
pro tvůrce primárních šablon, kteří by chtěli pomocí těchto šablon přidat systému nové rysy.
Schémata jsou pouze v elektronické podobě v souborech docsys.xsd (schéma uzlů) a
index.xsd (schéma pro indexové dokumenty). V případě schématu docsys.xsd je nutné podotknout,
že jazykem XML Schema nelze zachytit integritní omezení kladená na obsah tagu
docsys:documentation, takže tímto schématem nelze plně validovat výsledné dokumenty.
56

DocSys: systm pro generovn dokumentace

Transkript

Podobné dokumenty

Návod k obsluze Přesné váhy - digitálne váhy

Tscale NHB - LESAK sro

O Kurtu GödelOVI …z Brna