Boost logo

Boost :

From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2007-06-23 02:45:37


I've been offline for a bit. But I was able to spend several weeks learning
DocBook. I must say I was really impressed with quality of this project. I
also tried to get a grasp of BoostBook and gave perfunctory look on
quickbook. Here I would like to share my thoughts on recent "doc update"

I. quickbook as documentation media.

  Why, oh, why don't we learn from our own mistakes. We just started to
realize the problem we got ourselves into with makesystem. And immediately
find new toy to play with. However fun it is, however cool it might look on
first sight, THIS IS NOT OUR BUSENESS to invent/support documentation

 DocBook is very mature, well supported project. It's based on widely
accepted/supported technologies. It's powerful and configurable to implement
essentially anything one need. I personally don't see much valid reasons to
look in home grown format direction. Here some specific points:

1. Simplicity
       Some people argues that it's easier to type quickbook I might argue
that it's actually opposite. Granted if you use vi XML editing is not fun.
But myriads of modern XML editors simplify the process marginally. There
several WYSWYG editors producing DocBook (and I don't need to enter markup
at all!) and this trend is going to grow. In addition you get immediate
format validation and presentation (using assigned stylesheets)

2. Any change in DocBook have to be reflected in quickbook terms

3. Someone need to maintain quickbook parser/transformer

4. quickbook will never be as flexible as DocBook

5. This is new *nonstandard* format any new developer will have to learn. I
don't believe we can afford yet another barrier for new submitters.

6. Source code highlighting
      My understanding is that quickbook presents some source code
highlighting automation. IMO this can be either implemented as standalone
C++ based tool that docs writers can use when required or even better it can
be implemented in JavaScript. I believe I've seen it done.

 All in all I believe using this format is going to be a maintenance problem
in a long term and should be avoided. We should stick with industry standard
DocBook IMO instead.

II. BoostBook

1. Complexity
   The BoostBook being an extension to DocBook seems to be doing too much.
IMO any useful generic innovations should be proposed to the DocBook
developers and eventually removed. All in all we should strive to make this
layer as thin as possible.

2. Test suites support.
  I did not really grasp the idea behind this feature completely, but from
what I understand this is "misfeature" and should be removed

3. Tight coupling with Boost.Build
This is major problem I believe. Especially in documentation. BoostBook
should be presented as independent project. It should be explained how to
use it, configure it without any reference to Boost.Build at all. At the
very last chapter of documentation we may refer that if you want you docs to
be automatically generated on some remote host (if let's say you don't have
all the tools set up locally for all the formats) this is what you need to
do .....

4. Documentation
I found documentation to be largely unacceptable (funny thing for the
project dedicated to writing documentation)

  a) No explanation how to use BoostBook without Boost.Build (see above)

   b) all he elements description are without examples

    c) most critical: no description whatsoever of all the modification done
in comparison with DocBook. All the updated parameter need to be listed, all
the updated templates need to be explained. General approach should be what
the person familiar with DocBook (standard) need to know/expect to use

    d) No explanation on how to extend the BoostBook (especially in
comparison with DocBook)

As I mentioned before we should try to limit our extensions to the most
necessary only and strive to stick with standard DocBook. Also all
extensions should be made optional.

III. What should we do?

IMO the standardization efforts need to target DocBook/BoostBook. On the
other hand each developer should be allowed to extend/twick standard L&F.
Usually differences should be only cosmetic. Following are general
observations about common L&F

1. JS Menu support.
   I believe it should be implemented but made optional. I personally don't
like it (I believe it's just wait of space for this menu to stay on all the
time) and prefer "location path" kinda navigation Boost.Test currently

 2. Header on top.
   I don't believe it's necessary. Neither in a form of
boost|libraries|more|... nor what is currently proposed. This information
is accessible from boost main page. No need to duplicate it on every page of
every library.

  3. Frames
  I personally need frames support for the reference like pages (like in
preprocessor and test libraries). I am open to the alternative that presents
similar L&F.

  4. Portability
  This is major requirement for all the features we implement. They should
work on at least set of predefined "major" browsers.

Please make this as discouraging comments to overall documentation efforts
movements. I just don't believe we move in right direction.



Boost list run by bdawes at, gregod at, cpdaniel at, john at