Šablóna pre HelpStudio 3 založená na MSDN Lightweight štýle

Hľadal som spôsoby ako jednoducho písať a spravovať dokumentáciu k softvérovému projektu. DocBook som hneď obišiel, keďže sa mi nechcelo písať ručne XML značky. Preferujem, aby som hneď videl naformátovaný výsledok (potrebujem „Word experience“). Visual Studio 2005 SDK obsahuje HelpStudio Lite, čo je voľne dostupná verzia WYSIWYG editora dokumentácie, ktorý dokáže vygenerovať MSHelp 2.x súbory (to sú .HxS a podobné balíčky dostupné s Visual Studiom 2005 a 2008 v ktorých je dokumentácia a prezerajú sa pomocou Document Explorera).

MSDN 2010 Template for HelpStudio 3

Druhá moja požiadavka bola môžnosť upraviť si výstup tak, aby pripomínal nový MSDN Lightweight štýl – ten fialový branding MSDN knižnice. HelpStudio Lite umožňuje vytvoriť si vlastné šablóny a štýlovanie pre HTML stránky, ale aj podporné súbory pre MSHelp (index dokumentov, navigácia, atď.). Šablóny sú obyčajné HTML súbory s vloženými špeciálnymi značkami označujúci miesta, kde sa majú vložiť údaje z dokumentácie. Samotné dáta sú uložené v HelpStudio projekte – .hsp – čo je XML súbor obsahujúci celú vytvorenú dokumentáciu.

<!--DXMETADATA start type="Stylesheets" --><!--DXMETADATA end-->
<!--DXMETADATA start type="ProjectTitle" -->Project Title<!--DXMETADATA end -->

Šablóny sa v pohode dajú upravovať v editore ktorý je súčasťou HelpStudia. Ja som však využil Dreamweaver, lebo sa v ňom oveľa ľahšie čistil kód a robili štýly.

Nevýhoda Lite verzie je nutnosť výstupu iba do MSHelp 2.x verzie. HS 3 vie spraviť aj HTML výstup. Je to však také krkolomné: treba vypnúť zmazanie vygenerovaných HTML súborov. Balíčky MSHelp totiž obsahujú HTML dokumenty a HS v prvej časti kompilácie vygeneruje HTML obsah a ten v druhej fáze spojí do balíčka .HxS. S prechodom na HS 3 prišli aj trošku problémy: najprv nedokázal rozpoznať moju šablónu, pretože config.xml súbor obsahoval starú definíciu šablóny a HelpStudio ju nevie automaticky prekonvertovať. Druhý problém bol podobný. Definícia tzv. HTML Scraps je síce stále uložená v .txt súbore ale z textovej definície prešli na nový XML formát a síce šablóny fungovali s pôvodnou verziu, niektoré premenné generovali len tak rôzne XML fragmenty do HTML kódu.

Samotnú šablónu som uverejnil na Google Code hostingu ako hs3msdn2010tem­plate projekt pod BSD licenciou. Ako verziovací systém som zvolil Mercurial, pretože si myslím že umožní prípadným používateľom tejto šablóny oveľa jednoduchšie lokálne verziovanie kódu. Stačí si stiahnuť binárky a zadať tento príkaz na „naklonovanie“ zdrojákov:

hg clone https://hs3msdn2010template.googlecode.com/hg/ hs3msdn2010template

Síce HelpStudio Lite a 3 má veľkú výhodu vo vizuálnej editácie dokumentácie, slušné HTML editory, kontrolu pravopisu, rôzne podporné nástroje a jednoduché rozhranie, má aj veľa nevýhod a problémov: nezdokumentované šablóny, kompilácia je nechutne pomalá, občas padne a predávajú ho za nekresťanských cca 350? za 1 licenciu. Preto teraz študujem možnosti projektov Sandcastle a DocProject. Ale o nich nabudúce.