Re: [Boost-docs] some doc nits

Subject: Re: [Boost-docs] some doc nits
From: Steven Watanabe (watanabesj_at_[hidden])
Date: 2010-06-12 06:25:47

AMDG

Eric Niebler wrote:
> On 6/12/2010 1:56 AM, Eric Niebler wrote:
>   
>> My messages to this list are bouncing for some reason.
>>     
>
> Wow, strange. OK, here's the original:
>
> Just some doc nits, for anyone with the time, interest and xslt chops.
>
> There's a problem with how the xslt is dealing with <purpose> elements
> for classes. See the synopsis I just generated for a class with two
> nested classes:
>
> http://boost-sandbox.sourceforge.net/libs/proto/doc/html/boost/proto/domain.html
>
> There's a lot that has gone wrong here. It seems whitespace matters when
> it probably shouldn't. Lines aren't broken sensibly, and when they are,
> they aren't preceded by // to indicate they're a comment. Perhaps this
> is my bad for writing a <purpose> that doesn't fit on one line, but that
> doesn't seem like an unreasonable thing to do.
>   

I'd guess we're just getting the default behavior, since no-one
has tried to do this before.

> Also notice how some comments don't get syntax highlighted, like the 3
> occurrences of "// types" and "// public member functions".
>   

Okay.

> And as I've pointed out before, code that started out as a
> <programlisting> (e.g. the Example in the description) doesn't get
> highlighted at all.
>   

I can highlight it.  However, there are a couple issues
that need to be dealt with first
a) Is it safe to assume that every programlisting is C++?
    I don't think it is.
b) Quickbook currently does its own highlighting

> The source xml for this page can be found here:
>
> https://svn.boost.org/trac/boost/browser/trunk/libs/proto/doc/reference/domain.xml
>
> Finally, I noticed a strange CSS thing with free functions. See this page:
>
> http://boost-sandbox.sourceforge.net/libs/proto/doc/html/header/boost/proto/deep_copy_hpp.html
>
> Notice that the identifier for the deep_copy function is actually a
> link, but is not colored like a link. Odd.
>   

The CSS is out of date.  I fixed this in the trunk.

In Christ,
Steven Watanabe