1 Systém pro generování dokumentace DocSys Uživatelská příručka Výklad jazyka pro tvorbu dokumentace2 3 1. Úvod Principy dokumentování Úvod do dokumen...
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()" @ Funkce zkopíruje řetězec. ...
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); /** <@ Funkce zkopíruje řetězec. ...
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
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: První buňka HTML tabulky; díky break-marks bude tabulka naformátována ve zdrojáku vždy hezky 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.
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 tag, který má implicitně namespace docsys. <docsys:b>Zde je jeho ekvivalentní varianta. Tento <nondocsys:b>tag není standardním tagem, ale má být bez namespace. Ani tento tag není standardním tagem – namespace se mu však zachová.
Jeho podoba po aplikaci uvedených pravidel bude následující. Toto je <docsys:b>tag, který má implicitně namespace docsys. <docsys:b>Zde je jeho ekvivalentní varianta. Tento tag není standardním tagem, ale má být bez namespace. Ani tento tag není standardním tagem – namespace se mu však zachová.
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)]
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 odstavec 2 odstavec 3 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 <docsys:para>odstavec 2 odstavec 3 odstavec 4
V příkladu je vidět spojení druhého a třetího odstavce, aby nedošlo k překřížení značky s tagem para. Čtvrtý odstavec nesmí být uzavřen do tagu para, ale může jím být ukončen, protože ukončí párováním s narušující dvojici. Příklad: Opět je uveden fragment zdrojového kódu s využitím layoutu: odstavec 1 odstavec 2 odstavec 3 odstavec 4
A bez něj s použitím tagů para: <docsys:para>odstavec 1 odstavec 2 odstavec 3 <docsys:para>odstavec 4
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: První hodnota Popisek první hodnoty. Druhá hodnota Popisek druhé hodnoty. 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>Popis <docsys:tr> <docsys:td>První hodnota <docsys:td>Popisek první hodnoty. <docsys:tr> <docsys:td>Druhá hodnota <docsys:td>Popisek druhé hodnoty. Zde pokračuje odstavec.
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: [(text odkazu)] [(text odkazu)]
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: (neformátovaný text)
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): #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; }
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: (seznam paragrafů pro jednu položku) ...
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: 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. A tady už začíná druhá položka. Pokud bude text ve stejném paragrafu, jako tag item nebo itemstop, bude ztracen – takto to nepoužívejte! 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.
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.
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 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>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>Podpoložka b) položky 2.
5.2.3 Tabulky s pevným počtem sloupců Syntaxe: 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. 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
Prostě nula. Jednička.
0 1
23
5.2.4 Tabulka s proměnným počtem sloupců Syntaxe: [ (paragrafy tvořící záhlaví tabulky) ] [ (paragrafy tvořící řádek) ] ...
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. První buňka záhlaví. Druhá buňka záhlaví. První buňka. Třetí buňka.
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.
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)
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: (text odkazu)
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:
[
První hodnota Popisek první hodnoty. Druhá hodnota Popisek druhé hodnoty. <docsys:table> <docsys:tr style="table-header"> <docsys:td>Hodnota <docsys:td>Popis <docsys:tr> <docsys:td>První hodnota <docsys:td>Popisek první hodnoty. <docsys:tr> <docsys:td>Druhá hodnota <docsys:td>Popisek druhé hodnoty.
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: [
[(obsah položky)]
...]
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)"}
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.
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
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:custom-properties> [<docsys:property name="(jméno property)" value="(hodnota property)" /> ...] <docsys:content> (vlastní obsah dokumentu)
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.
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.
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 , 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" />
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" />
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-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" />
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 char="I" /> ... <docsys:char-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" />
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:documentation> <docsys:section name="(jméno sekce)"> ... ...
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:desc> Tato funkce je členskou funkcí jedné nejmenované třídy. <docsys:member> <docsys:linktext> <docsys:link target-id="node.01FC9680"> AnotherMethod() <docsys:desc> Tato funkce je další členskou funkcí jisté nejmenované třídy. <docsys:member-group type="public-variables"> <docsys:member> <docsys:linktext> <docsys:kw>int <docsys:link target-id="node.01ADE680">A <docsys:desc> Veřejná proměnná... opět od jedné nejmenované třídy. ...
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> intfunkce<sym>(A<sym>& parametr<sym>); <docsys:declaration> intfunkce<sym>(intparametr<sym>); ...
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)"> ... ...
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 kořenový adresář 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 ').
: __[_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.
