Re: [boost] Boost documentation

From: David Abrahams (dave_at_[hidden])
Date: 2007-07-01 21:24:18

on Sun Jun 24 2007, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:

> David Abrahams wrote:
>> on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
>
>>> 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.
>
> DocBook is designed for extensibility. 

I know.  That's why I said *builtin*.

BoostBook is just an extension of DocBook, using expressly-designed
hooks in DocBook for that purpose.  I don't consider that an NIH move
on our part; quite the contrary.

>> How well will these WYSIWYG editors handle BoostBook's special tags?
>
> I'm not aware of fany DocBook editors, only XML editors. And these don't
> notice 'special tags'. You feed them a document type (DTD, RelaxNG, XSchema, etc.),
> and they Just Work.

Yeah, well Gennadiy cited WYSIWYG.

>> Which editors are these, BTW?
>
> The one I have run across is xxe (http://www.xmlmind.com/xmleditor/). But
> I'm mostly using (x)emacs, which has its own xml-editing modes that will
> happily accept any customization layer, too.

Yeah, that's fine too; I use emacs.  It's just not quite
WYSIWYG... not that it's a problem for me.

>>> 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.
>
> There are other standard languages that could be used as a mixin, such
> as ReST. 

Yes.  Big fan here.  C++ TMP and the MPL reference and Boost.Parameter
docs and the new getting started guide were all written in ReST.

> The point is not only syntactical ease. But having independent
> development / maintainence, documentation, etc., is
> invaluable. That's essentially the first argument above.

Yes, it's huge.  Someone else wrote an emacs editing mode for ReST
that works great.  I had to try to write a qbk-mode.  It took a long
time.  It doesn't work great.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com
The Astoria Seminar ==> http://www.astoriaseminar.com