"John Maddock" <[EMAIL PROTECTED]> writes:
> David Abrahams wrote:
>> I wish I had time to write this message right, so pardon my clumsy
>> delivery.
>>
>> QB has quite a few advantages in terms of semantic capability,
>> especialy where C++ is concerned. On the other hand:
>>
>> I think ReST designers have devoted a little more effort to keeping
>> the documents readable as plain text. I wonder if we can learn
>> anything from them there?
>>
>> ReST is written in Python, which is IMO a far superior language to
>> C++ for DOM traversal/manipulation (it's too dynamically polymorphic
>> a problem to be handled nicely in C++ IMO). Maybe we should be
>> thinking about slapping a Python backend on QB?
>
> Gosh, Python with everything :-)
>
> I see where you're coming from, but having only scanned the reST docs, it
> seems like there's already a lot of similarity between reST and quickbook,
> the main differences seem to be:
>
> Links: at present I think I prefer quickbook.
I think there's something attractive about being able to write Boost_
and have that be a link to Boost. Of course you can get the same
effect in quickbook, but it requires writing a macro first. On second
thought it might not be any harder than in ReST.
> Tables: I have problems with quickbook tables once they have more than a few
> elements, on the other hand I don't particularly want to start writing ASCII
> art in the reST way either: though I accept it's good to look at, I wouldn't
> want to come back later and try and insert more text into the middle of a
> big table.
With emacs table mode it's pretty easy, actually.
>
> Sections: I'm perfectly happy with quickbook here, although our chunking
> needs tweeking a bit.
I *really* like ReST section titles. Seeing
[h1 The Way It Is]
is nowhere near as meaningful as plaintext as
===============
The Way It Is
===============
Just take a look at http://boost.org/libs/parameter/doc/index.rst to
get a feel for what real documents look like.
> Footnotes/references: reST looks superior here (you can define a footnote
> the first time you use it, and then refer to it from multiple locations), we
> really need this one :-)
yeah, footnotes are crucial
> macro/templates: reST doesn't have them?? Presumably you use a python
> script to extend the engine
No, that's an area where ReST is philosophically and intentionally
limited. It's supposed to be a document format and *not* a
programming language. It does have "substitution references"
(http://docutils.sourceforge.net/docs/ref/rst/directives.html#directives-for-substitution-definitions)
but I don't think it will go further.
I much prefer QB's direction here.
> Images: reST has more control it appears to me, at present quickbook doesn't
> even begin to touch what DocBook can do (for example providing alt text plus
> eps for PDF's and png for HTML output), however a template would do the
> trick quite nicely here.
>
> Anything I've missed?
Probably a lot. There's a lot more to ReST than I can keep in my
mind. See
http://docutils.sourceforge.net/docs/ref/rst/directives.html among others
--
Dave Abrahams
Boost Consulting
www.boost-consulting.com
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
