User documentation for Fantasdic
Yesterday I’ve added user documentation support to Fantasdic, as can be found in the Help > Contents menu of most GNOME applications. This is not an area developers are generally willing to spend much time for because what is documented sometimes sounds like trivial (“to look up a word in the dictionary, enter your word in the search entry and press enter”) but I think that this is definitely important for adoption of Fantasdic in major distributions. Writing comprehensive, concise and clear documentation, in addition to adding all the required infrastructure in the program, is in itself a difficult exercise so I ended up spending a fair amount of time for that. I also improved my knowledge of Docbook and learned about scrollkeeper and OMF while doing it. I definitely didn’t waste my time.
When available, the documentation is displayed using yelp, the GNOME help viewer, otherwise (Windows, KDE) the HTML version of the documentation is displayed in the default browser.
Oh, by the way, the documentation is not yet totally complete, so here’s a bunch of useful commands if ever you’re willing to help with documentation:
Check the validity of the document:
$ xmllint –noout –noent –valid fantasdic.xml
Transform the document:
$ xsltproc –noout -o output stylesheet.xsl fantasdic.xml
Visualize the document:
$ yelp -p /full/path/to/fantasdic.xml
Create a .po (translation) file:
$ xml2po -o LANG.po ../C/fantasdic.xml
Merge back the changes to fantasdic.xml:
$ xml2po -p LANG.po -o fantasdic.xml ../C/fantasdic.xml
Update an existing .po file:
$ xml2po -u LANG.po ../C/fantasdic.xml
Convert to HTML:
$ xmlto -o html-dir html fantasdic.xml