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-05-16 17:55:24

on Mon Apr 28 2008, David Abrahams <dave-AT-boost-consulting.com> wrote:

> 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?*

Serious question; I'm not trying to be snarky.  If you simply used the
wrong word to describe what you mean, please try to clarify.

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

Rene, I think this issue is too important to let it lie.  C++ is a
case-sensitive language.  We simply can't have this kind of confusion in
our documentation.  Please, at the very least, implement the compromise
solution ASAP.

As to going further, I'd be willing to wager that we have plenty of docs
where C++ code has not been diligently wrapped in <pre> or <tt> in
section titles, so even if you disagree with the ideas below, I think
you ought to consider removing all the small-caps stuff as a stopgap
measure until you can verify that the docs have been written with that
discipline in mind.

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

Thanks,

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com