Hlavní navigace

Budoucnost dokumentace pro OSS

Jirka Kosek

Bez dobré dokumentace by se praktická použitelnost mnoha programů výrazně zmenšila. Platí to samozřejmě i pro open source aplikace. V neděli 22. července se proto v San Diegu ještě před začátkem konference O'Reilly Open Source Convention sešly významné osobnosti z dokumentačních projektu a vývojáři nástrojů pro zpracování dokumentace na Documentation Summitu.

Sumit se konal již podruhé a sešlo se na něm 20 lidí. Z těch známějších jmenujme například Normana Walshe (autor stylů pro formátování docbookových dokumentů, předseda technické komise DocBooku), Erica S. Raymonda (toho určitě znáte zejména jako autora eseje Bazar a katedrála), Erica Bishoffa (vedoucí dokumentačního týmu KDE), Nika Claytona (vedoucí dokumentačního týmu FreeBSD) a Guylhema Aznara (koordinátor LDP – Linuxového dokumentačního projektu). Mezi dalšími účastníky nechyběli zástupci dalších projektů a firem – Gnome, RedHat, Caldera, DocBook Open Repository, O'Reilly Associates.

Zatímco jádrem loňského sumitu byla diskuse o nejvhodnějším formátu pro tvorbu dokumentace, letos šlo spíše o řešení specifických praktických problémů spojených s licencemi pro dokumentaci, použitím nástrojů, motivováním autorů atd.

Většina open source projektů dnes pro tvorbu dokumentace používá DocBook. DocBook je systém založený na XML/SGML, který umožňuje strukturovaný, sémantický zápis mnoha druhů dokumentů – knihy, články, manuálové stránky, reference apod. Existují volně dostupné styly, které umožňují konverzi docbookových dokumentů do dalších formátů jako HTML, PDF, PostScript a RTF. Projekty KDE, Gnome a FreeBSD dnes už používají výhradně DocBook. LDP je do DocBooku převeden ze 43 %, ostatní dokumentace ještě používá starší formát LinuxDoc. DocBook podporuje i FSF (Free Software Foundation), která pro tvorbu dokumentace používá vlastní formát Texinfo.

Asi nejvzrušenější debatu vyvolala otázka licencí pro dokumentaci. Z mnoha důvodů není dobré používat stejné licence jako pro software. Mezi nejznámější licence patří FDL (GNU Free Documentation License) a OPL (OpenContent License), velmi liberální je BSD licence pro dokumentaci. Zjednodušeně řečeno, první dvě licence umožňují bezplatné šíření dokumentace v elektronické podobě, s tím že zejména FDL chrání právo autora a nakladatele vydat knihu v papírově podobě, a vydělat si tak na živobytí. Podle některých účastníků by bylo vhodné pro dokumentaci používat jednu licenci – umožnilo by to bezproblémové kombinování částí dokumentace mezi jednotlivými projekty. K tomu však z praktických důvodů nedojde. Například FDL vyžaduje uvedení licenčních podmínek v každém dokumentu. Představte si tedy, že by na konci každé manuálové stránky bylo sedm nebo snad ještě více obrazovek licence. Doufejme, že k tomu nedojde. Jako nejlepší řešení se jeví použití licencí jako FDL/OPL pro delší dokumenty – dokumentace rozsahu knihy a větší. Pro menší dokumenty (manuálové stránky, krátké HOW-TO), kde autor ani neočekává žádnou zvláštní ochranu nebo vydání dokumentu v knižní podobě, je pak vhodné použít krátkou a liberální licenci ve stylu BSD.

Nakladatelství O'Reilly již několik knih pod FDL dokonce vydalo a rádi by vydali ještě další. Takže jestli máte nějakou knihu hotovou v šuplíku, klidně je kontaktuje, tvářili se velmi otevřeně. Pro příznivce DocBooku je dobrou zprávou, že oficiální dokumentace – kniha DocBook The Definitive Guide – byla rovněž uvolněna pod FDL. Kniha byla v elektronické podobě dostupná i dříve, ale uvolnění pod FDL umožní její překlad do dalších jazyků (nějací dobrovolníci pro překlad do češtiny? ;-) bez nutnosti platit licenční poplatky nakladateli.

Problémem, který trápí mnoho dokumentačních projektů, je nedostatek autorů dokumentace a překladatelů do dalších jazyků. Podle zkušeností mnoha účastníků existuje pro autory dokumentace celkem velká motivace. Většina uživatelů nějakého softwaru kontaktuje při problémech autora dokumentace, a ne přímo autora produktu. Takovéto promasírování ega může být pro mnoho autorů dokumentace dostatečnou odměnou. Bariérou pro některé potencionální autory může být na první pohled větší složitost DocBooku. Pro usnadnění konverze stávající dokumentace vznikají aplikace umožňují konverzi mezi DocBookem a formáty Texinfo a LinuxDoc.

Největší bolestní je absence dobrého vizuálního XML editoru. Jistou naději skrývají projekty jako Getox a Conglomerate. Pro uživatele Emacsu existuje dosud nepřekonaný editační režim PSGML, ale buďme upřímní – Emacs není editor pro každého (totéž však můžeme říci i o vi;-).

Na pořad jednání se také dostaly nástroje, které lze použít pro transformaci DocBooku do výsledných formátů jako je např. HTML a PDF. Z volně dostupných nástrojů jsou nejpoužívanější především XSL a DSSSL styly. DSSSL je formátovací a transformační jazyk poněkud staršího data a existuje jen jedna jeho implementace – Jade a její pokračovatel OpenJade. Pro zpracování XSL stylů je potřeba XSLT procesor. Těch dnes existuje několik. Do budoucna bude mezi nejpoužívanější procesor patřit nejspíš nově uvolněná knihovna libxslt, která je velmi rychlá v porovnání s javovými implementacemi XSLT, jako je Xalan a Saxon. XSLT lze použít pro konverzi DocBookového dokumentu do HTML nebo do formátovacích objektů (FO). Formátovací objekty jsou XML dokument, který abstraktním způsobem popisuje vzhled stránky. FO mohou být zpracovány nějakým formátovacím programem, který z nich vytvoří například PDF nebo PostScript. Open source implementace FO procesorů (FOP, JadeTeX) však ještě nejsou zdaleka dokonalé. Vyvíjejí se však poměrně rychlé, takže brzy snad dosáhnou potřebné kvality. Následující obrázek, jehož autorem je Eric S. Raymond, znázorňuje možné cesty pro získání jednotlivých výstupních formátů z docbookového dokumentu.

schéma

Jediný problém volně dostupných nástrojů je kvalita tištěného výstupu. Ta nemusí být pro potřeby všech uživatelů dostatečná. Nik Clayton říká, že použití DSSSL a Jade však dává uspokojivé výsledky pro dokumentaci OS projektů. Můžete se sami přesvědčit, dokumentace k FreeBSD je vytvořena právě tímto způsobem.

Z nástroji úzce souviselo vystoupení Erica Bischoffa o použití překladových pamětí při překladech dokumentace z angličitny do dalších jazyků. KDE tým vyvinul nástroj po2×ml, který umožňuje vzít docbookový dokument a inteligentně ho rozseká na řetězce, které se pak uloží do běžného po souboru používaného knihovnou GNU gettext. Po přeložení dokumentace se pak pomocí po2×ml opět získá docbookový dokument, tentokráte však s přeloženou verzí dokumentace.

Na program sumitu se dostala i budoucnost DocBooku. Příští verze 5.0 by měla být uvolněna ještě tento rok a bude dostupná stále ve dvou verzích – XML a SGML. Jak však řekl N. Walsh „SGML is dead“ – je tedy jen otázkou času, kdy přestane být dále vyvíjena SGML verze DocBooku. Další problémem je podpora jmenných prostorů v XML verzi DocBooku. V současné době je DocBook definován pomocí DTD, to však nepodporuje jmenné prostory. Bez plné podpory jmenných podporů je těžké vkládat do DocBooku například obrázky v SVG nebo matematické výrazy v MathML. Problém by vyřešil přechod z DTD na jiný formát pro popis schématu dokumentu – např. na XML schémata nebo Relax NG. V současné době není možné podporu DTD ukončit, protože bez ní by nefungovaly mnohé XML/SGML editory. Norm plánuje v budoucnosti definovat syntaxi DocBooku v jazyce Relax NG a vytvořit XSLT styl, který z tohoto popisu automaticky vegeneruje ekvivalentní DTD.

Modním hitem posledních let jsou i metadata. DocBook obsahuje několik elementů pro zápis metadat, ale jeho vyjadřovací schopnosti jsou menší než např. dnes velmi rozšířený standard Dublin Core. V budoucích verzí DocBooku proto bude pravděpodobně rozšířena podpora metadat, inspirována bude zejména Dublin Corem a projektem OMF.

Nedá se říci, že by Documentation Summit něco zásadního vyřešil. Sešli se na něm však lidé, kteří jsou vůdčí osobnosti v tvorbě dokumentace. Navzájem se informovali o svých problémech i úspěších. Ujasnili si směr, kterým se bude dokumentace dále vyvíjet a jaké problémy je potřeba vyřešit. Jedno je však jasné – jestli vytváříte dokumentaci a používáte k tomu něco jiného než XML a DocBook, jste na špatné koleji. Alespoň takhle by vám to řekla většina účastníků sumitu včetně mne.

Našli jste v článku chybu?

8. 8. 2001 16:13

kargee dušek (neregistrovaný)

takže pojďme přeložit zase kousek manuálů do češtiny
czman-help@linux.cz
czman@linux.cz



6. 8. 2001 9:53

Luděk Rašek (neregistrovaný)

MathML lze editovat v prohlížeči Amaya (http://www.w3.org/Amaya/) možná je to dokonce jediná věc, pro kterou je Amaya použitelná v praxi :-). Nějaké zkušenosti ?

Podnikatel.cz: K EET. Štamgast už peníze na stole nenechá

K EET. Štamgast už peníze na stole nenechá

Podnikatel.cz: Změny v cestovních náhradách 2017

Změny v cestovních náhradách 2017

DigiZone.cz: TV Philips a Android verze 6.0

TV Philips a Android verze 6.0

Lupa.cz: Teletext je „internetem hipsterů“

Teletext je „internetem hipsterů“

Vitalia.cz: Taky věříte na pravidlo 5 sekund?

Taky věříte na pravidlo 5 sekund?

Měšec.cz: Air Bank zruší TOP3 garanci a zdražuje kurzy

Air Bank zruší TOP3 garanci a zdražuje kurzy

Vitalia.cz: Potvrzeno: Pobyt v lese je skvělý na imunitu

Potvrzeno: Pobyt v lese je skvělý na imunitu

Podnikatel.cz: Chaos u EET pokračuje. Jsou tu další návrhy

Chaos u EET pokračuje. Jsou tu další návrhy

DigiZone.cz: Rádio Šlágr má licenci pro digi vysílání

Rádio Šlágr má licenci pro digi vysílání

120na80.cz: Pánové, pečujte o svoje přirození a prostatu

Pánové, pečujte o svoje přirození a prostatu

Měšec.cz: Jak levně odeslat balík přímo z domu?

Jak levně odeslat balík přímo z domu?

Vitalia.cz: Jsou čajové sáčky toxické?

Jsou čajové sáčky toxické?

Vitalia.cz: Když přijdete o oko, přijdete na rok o řidičák

Když přijdete o oko, přijdete na rok o řidičák

Měšec.cz: Kdy vám stát dá na stěhování 50 000 Kč?

Kdy vám stát dá na stěhování 50 000 Kč?

120na80.cz: Co všechno ovlivňuje ženskou plodnost?

Co všechno ovlivňuje ženskou plodnost?

Vitalia.cz: Pamlsková vyhláška bude platit jen na základkách

Pamlsková vyhláška bude platit jen na základkách

Lupa.cz: Co se dá měřit přes Internet věcí

Co se dá měřit přes Internet věcí

Podnikatel.cz: Udávání kvůli EET začalo

Udávání kvůli EET začalo

Lupa.cz: Proč firmy málo chrání data? Chovají se logicky

Proč firmy málo chrání data? Chovají se logicky

120na80.cz: Na ucho teplý, nebo studený obklad?

Na ucho teplý, nebo studený obklad?