Re: [Boost-docs] some doc nits

Subject: Re: [Boost-docs] some doc nits
From: Eric Niebler (eric_at_[hidden])
Date: 2010-06-12 12:07:42

On 6/12/2010 2:25 AM, Steven Watanabe wrote:
> AMDG
> 
> Eric Niebler wrote:
>> 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.

Actually, I have. I've had to rejigger my <purpose> to account for the
poor handling on several occasions. This time, I couldn't make it any
pithier and got to feeling like I prolly shouldn't have to.

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

Good point.

> b) Quickbook currently does its own highlighting

Not sure what you mean here. This isn't a quickbook file.

>> Finally, I noticed a strange CSS thing with free functions. See this
>> page:
<snip>
> 
> The CSS is out of date.  I fixed this in the trunk.

Ah. You're prescient. Thanks for fixing it before I knew it was a problem.

-- 
Eric Niebler
BoostPro Computing
http://www.boostpro.com