[haiku-doc] Future plans for Haiku user documentation
- From: Patrik Gissberg <patrik@xxxxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Tue, 15 Nov 2011 11:42:21 +0100
Copy of e-mail sent to haiku-web@xxxxxxxxxxxxxx
Hi
I've been working with the Haiku User Documentation Translator for a few
days which has made me learn little about how it works. Sadly, I have to
say that I have identified a lot of future obstacles.
- First of all, the tool is quite messy codevise. It is difficult to change.
- No support for versioning (ie R1, R2 etc). Very difficult to implement!
- The documentation is hard-coded in html.
- Documentation cannot be exported to other formats, such as pdf's.
- Layout changes (or similar) must be changed _manually_ in every
document (except for css).
I would suggest that we start looking into alternatives. I would
strongly suggest that we use DocBook for markup hosted on a central
repository for revision control. Any DocBook editor will work for editing.
Gettext should be used to generate .po files that can be imported into
Pootle. This way, translators can work with Haiku interface and
documentation localization using the same tool. That's a win-win!
Different versions could then be generated, like one page and multi-page
html and a pdf book, which could even be printed and sold, generating
revenue.
I think this is the proper way to go. A lot of work, but definitely less
than rewriting our current tool. And it's future proof!
Good introduction to DocBook:
http://www.informatik.tu-cottbus.de/~agiurca/tutorials/DocBook/index.htm
Patrik
Other related posts:
