From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2007-06-25 01:36:38
"David Abrahams" <dave_at_[hidden]> wrote in message
>> There several WYSWYG editors producing DocBook (and I don't need to
>> enter markup at all!) and this trend is going to grow.
> Yeah, but we need to represent semantic information (e.g. Concepts)
> that are outside the builtin representational abilities of DocBook.
> How well will these WYSIWYG editors handle BoostBook's special tags?
> Which editors are these, BTW?
look for WYSWYG
>> 4. quickbook will never be as flexible as DocBook
> Disagree. It's far more flexible, because it has a whole macro
> language builtin.
>> 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
> Unless they already know DocBook, DocBook represents a much higher
> barrier for most people getting started.
I would guess that number of people familiar with DocBook would be much more
in comparison with QuickBook
>> 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.
> I don't think it's necessarily that clear-cut. However, there *are*
> other broadly-accepted tools, supported by others, (e.g. docutils)
> that we can use to produce DocBook, so it doesn't necessarily mean
> we're stuck with XML as our input format if we don't want to have to
> support our own front-end.
I don't believe boost should regulate what people use to develop docs. What
it should regulate is: what people need to use the docs. IOW what we should
require is the presence of BoostBook file in a doc directory (under source
control and in deliverables). At that point it's irrelevant how you got it
(using XML editor, QuickBook or any other way). BoostBook document I can use
to do whatever I want with it. Including producing my own personal form of
documentation based on my company requirements or change a L&F if it matters
IOW we should state: Boost documentation is in BoostBook format and you
need to know it (and corresponding tools) to work with it (well almost:
release provides regular output in a form of HTML). The BoostBook document
should be the one required during review.
What we shouldn't do IMO is to require yet another tool to work with
documentation. And HTML generation should be strait from BoostBook
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk