Re: [boost] Boost documentation

From: Stefan Seefeld (seefeld_at_[hidden])
Date: 2007-06-24 15:59:58

David Abrahams wrote:
> on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:

>>   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 
>> format.
> 
> That's a concern for me, I must admit.

I'm glad to hear that.

>> 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. That's becoming even more true
with the new DocBook 5. It is possible to refine the document type (e.g.
add custom vocabulary), as well as add custom (xslt) templates to be
used in the processing pipeline when generating html, pdf, etc.

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

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

[...]

>> 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. The point is not only syntactical ease. But having independent
development / maintainence, documentation, etc., is invaluable. That's
essentially the first argument above.

>> 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.
> 
> I *seriously* doubt DocBook is going to accept C++-specific tags such
> as we use for concept documentation.

I had some discussions with Norman Walsh over the years, when I realized
that DocBook was a bit inconsistent in its support for language-specific
artifacts. The tricky thing is that DocBook is a documentation language,
not a modeling language. I do believe it would be good to be able to represent
more language artifacts (I have a hard time deciding what kind of DocBook to
generate with my Synopsis reference manual generator), but I understand
the concern about language bloat that may incur, at least if these changes
got into the core vocabulary.

Regards,
                Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...