Livedocs

Školení, která pořádám

Pokud jste někdy reportovali dokumentační bug, mohli jste být svědky toho, že byl nejprve opraven v CVS a teprve po několika týdnech nebo měsících se objevil na webu. To je i případ uživatelských poznámek zakomponovaných do manuálu a smazaných. Důvod je ten, že se HTML podoba manuálu z Docbook zdrojáků generuje pomocí DSSSL stylů, což je časově poměrně náročný proces – při jakékoliv změně je nutné přegenerovat celý manuál, což trvá několik hodin. S přihlédnutím k tomu, že je manuál k dispozici v několika jazycích, by se mohlo generovat prakticky nepřetržitě, zohlednit je nutné i přenos nových souborů na všechna zrcadla. Za ruční aktualizací manuálu je asi i trochu politiky – zabrání se tím tomu, že by někdo v CVS udělal velkou změnu, která by se rychle dostala na stránky a tím by šel web svým způsobem hacknout.

DSSSL styly jsou i důvod, proč HTML zdroják manuálu nevypadá příliš vzhledně. Ne snad, že by to nešlo upravit, ale nikomu se do toho nechce. Pro převod do formátu CHM se používají XSL styly, ale přesný důvod, proč se nepoužívají i pro HTML verzi, neznám. Asi DSSSL styly řeší některé okrajové případy pořád lépe.

Budoucnost zveřejňování PHP manuálu má ale jméno Livedocs. Jedná se o systém generování HTML stránek z formátu Docbooku za letu. Jakákoliv změna ve zdrojácích se po smazání cache ihned projeví na výsledné stránce, což se při práci na dokumentaci báječně hodí, ale své ovoce to přinese i běžným uživatelům – především právě v rychlejší aktualizaci manuálu. Livedocs je koncert elegantnosti – do pár kilo přehledného kódu bez potřeby externích knihoven je vměstnán párvteřinový proces, který mnohamegabajtové nástroje řeší hodiny.

Ke stažení je i verze pro domácí použití, vše je ale dosud ve fázi alfa-testů. Zatím tedy ani není úplně vhodná doba na reportování bugů.

Jakub Vrána, Ze zákulisí, 16.11.2005, diskuse: 0 (nové: 0)

Vložit komentář

Používejte diakritiku. Vstup se chápe jako čistý text, ale URL budou převedeny na odkazy a PHP kód uzavřený do <?php ?> bude zvýrazněn. Pokud máte dotaz, který nesouvisí s článkem, zkuste raději diskusi o PHP, zde se odpovědi pravděpodobně nedočkáte.

Jméno: URL:

avatar © 2005-2018 Jakub Vrána. Publikované texty můžete přetiskovat pouze se svolením autora. Ukázky kódu smíte používat s uvedením autora a URL tohoto webu bez dalších omezení Creative Commons. Můžeme si tykat. Skripty předpokládají nastavení: magic_quotes_gpc=Off, magic_quotes_runtime=Off, error_reporting=E_ALL & ~E_NOTICE a očekávají předchozí zavolání mysql_set_charset. Skripty by měly být funkční v PHP >= 4.3 a PHP >= 5.0.