Re: [Boost-docs] [stylesheet] forced upcasing of titles

Subject: Re: [Boost-docs] [stylesheet] forced upcasing of titles
From: David Abrahams (dave_at_[hidden])
Date: 2008-04-28 15:17:01

on Tue Apr 01 2008, Rene Rivera <grafikrobot-AT-gmail.com> wrote:

> David Abrahams wrote:
>> It worries me that C++ identifiers appearing in section titles come out
>> as ALL_CAPS with the new documentation stylesheet.  This one is fairly
>> innocuous
>> (http://boost.org/doc/libs/1_35_0/libs/python/doc/building.html#include-issues)
>> but other cases could easily be really confusing.
>> 
>> Is the stylistic advantage of small-caps section titles worth the
>> potential confusion?
>
> Good question. I think the small-caps are useful overall. 

Useful?  How so?  I can understand you may like the way they look
better, but how can they be *used?*

> But I can see how it would be confusing in this case. Would a
> compromise of not showing the #include part of the heading as
> small-caps work? It would generically be showing any "pre" or "tt"
> within a header as-is.

It would help, I think.

That said, I think you ought to seriously consider whether small caps
are an appropriate stylistic thing to enforce globally.  Usually when
I've seen them used in print, they have been very selectively and
sparingly applied.  They might be used, for example, for a company name
or a book's title.

It seems to me that squashing the case out of section titles amounts to
an arbitrary limitation on what authors can express.

-- 
Dave Abrahams
Boost Consulting
http://boost-consulting.com