Re: [boost] Reference documentation: one approach

From: Jaakko Jarvi (jajarvi_at_[hidden])
Date: 2002-10-29 13:15:54

The lambda docs are written in DocBook. That was my first (and only thus 
far) experience on DocBook.
So here is my DocBook experience report.

- DocBook is very very verbose. I used xemacs, which has some shortcuts, 
and menus for various tags etc., but still there are a lot of tags to 
type/insert/...

- there was is a learning curve, it took a day or two to get going, and 
occasional stumbling on the way.

- customizing is not easy (compared to say \newcommand in latex)

- managing citations is better than in plain HTML but still a nightmare
  compared to latex/bibtex
  In theory one can have a bibtex like citation database in DocBook, but
  I couldn't find any tools for creating reasonable formats from such a 
  database, and I didn't have the time/expertise to start building my on
  stylesheets.

Comparisons:

DocBook vs. Plain HTML

  DocBook clearly wins. It makes managing internal links much easier, 
output is more consistent, you do not need to fix heading levels, ...

DocBook vs. Latex

  - Latex may have even longer learning curve, but more friendly to the
    author.
  - Latex is mature, more so than XML DocBook.
  - Latex tends to be geared towards producing paper output, rather 
    than something that can be rendered on screen with an unknown width.

Cheers, Jaakko