Re: [Boost-docs] The beauty of LATEX

Subject: Re: [Boost-docs] The beauty of LATEX
From: Daniel James (dnljms_at_[hidden])
Date: 2011-10-18 18:21:33

On 18 October 2011 04:12, Rene Rivera <grafikrobot_at_[hidden]> wrote:
>> The
>> implementation of the current quickbook is quite different though, the
>> spirit 2 version was very static, while the current version uses a
>
> Hm you meant spirt1 version was very static?

I was referring to how the parse results was stored. In the spirit 2
version I was binding the grammar to static data types (which was the
fashion at the time) and then overloading functions based on the type.
That resulted in quite attractive code but was a real pain to work
with (that isn't necessarily true in general). I deleted the branch in
subversion but it can be checked out with:

svn checkout https://svn.boost.org/svn/boost/branches/quickbook-1.5-spirit2@71148

And can be browsed online using the git mirror:

https://github.com/ryppl/boost-svn/tree/quickbook-1.5-spirit2

The current version stores it in a more flexible data type. The
implementation is very ugly in places but life is a lot easier.

>> There is another problem, much of the current documentation based on
>> doxygen + quickbook make use of tags like 'funcref' and 'classref' to
>> link into the doxygen documentation, a replacement would need
>> something to support that. I haven't really thought about doing that
>> in quickbook, could possibly add some sort of anchor for language
>> reference types, would need to build in some sort of namespace
>> resolution, and maybe a way to identify the language type (could just
>> use the source mode?). I'm not sure if it'd be a good idea.
>
> I just don't think it's needed. To be frank, the Doxygen like features, of
> "extracting" synthetic documentation from the code declarations is the last
> thing I want.

It isn't just about what you (or Joel) wants. Quite a lot of quickbook
documentation uses doxygen (not mine by the way). If we want to switch
to generating html, we'll need to provide a means of transition,
otherwise the uptake will be low.

And I was talking about linking not extracting. The idea is that if
you document a function in quickbook, you mark it with a function
anchor so that it can be easily linked to. I've found that linking to
functions by their symbolic name is actually a really nice feature. A
documentation generator could insert the anchors automatically. When
manually writing reference documentation they could be inserted by
hand. As I said, I'm not sure about it because I can see a few
possible warts.