Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-19 20:34:10

On Tuesday, 18 October 2011, Joel de Guzman wrote:

> On 10/19/2011 2:21 AM, Daniel James wrote:
>
> >
> > It isn't just about what you (or Joel) wants.
>
> You are the defacto maintainer of Quickbook now. What do you want?
>

I don't feel a strong ownership of quickbook, I'm currently driving
development but don't feel like I will automatically get new features
through or have a veto on anything (part of the reason for putting a version
switch on everything is so that language changes can be easily backed out if
rejected).

My main aim with quickbook has been to get what currently exists to work as
well as possible. I've been very conservative about adding new features but
a little radical with the implementation (I do worry that one day someone is
going to look at it and have a heart attack). My recent efforts have been to
improve the way quickbook structures the documentation - e.g. better id
generation, smarter placement of anchors, supporting docinfo in included
files. Once that's done (soon I hope, subject to approval), I want to
improve the grammar, for example change it so that square brackets are
always grammatical, unless they are escaped or in a code block (which should
fix a few of quickbook's quirks) and try to improve nesting of blocks (e.g.
paragraphs in lists and lists in tables).

I'm pretty wary about embedding a programming language in a documentation
format. My experience with such things has not been great. If you look at
XSL, it's great for some XML transformations, but when you try to do
something more complicated (you don't have to look far) it becomes a real
pain, I could see quickbook templates being similar. I would be more
interested in embedding an existing language by some means, but that isn't
something I'm planning on doing (I think it would really need to have a full
AST representation first, although maybe just section by section).

As for doxygen etc. I'd just want it to work well, without requiring it.
That's why I was discussing a more general idea of function links. Something
that can integrate with manual and automatic documentation of different
forms.