Re: [boost] Boost documentation

From: Gennadiy Rozental (gennadiy.rozental_at_[hidden])
Date: 2007-06-25 01:36:38

"David Abrahams" <dave_at_[hidden]> wrote in message 
news:87vedd16z5.fsf_at_grogan.peloton...
>> 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?

see here:
http://wiki.docbook.org/topic/DocBookAuthoringTools

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
>> submitters.
>
> 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 
for me.

   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 
documents.

Gennadiy