headers
David Abrahams | 30 Mar 23:37

[stylesheet] forced upcasing of titles


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?

--

-- 
Dave Abrahams
Boost Consulting
http://boost-consulting.com
Permalink | Reply |
headers
Rene Rivera | 1 Apr 18:48

Re: [stylesheet] forced upcasing of titles

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

--

-- 
-- Grafik - Don't Assume Anything
-- Redshift Software, Inc. - http://redshift-software.com
-- rrivera/acm.org (msn) - grafik/redshift-software.com
-- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail
Permalink | Reply |
headers
Eric Niebler | 1 Apr 19:02

Re: [stylesheet] forced upcasing of titles

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

I'll second Dave's call to nix the uppercasing of titles. I put 
identifiers in titles. C++ respects case. So should Boost's docs.

--

-- 
Eric Niebler
Boost Consulting
www.boost-consulting.com
Permalink | Reply |
headers
David Abrahams | 28 Apr 17:17

Re: [stylesheet] forced upcasing of titles


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.
(Continue reading)

Permalink | Reply |
headers
Paul A Bristow | 29 Apr 19:46

Re: [stylesheet] forced upcasing of titles


>-----Original Message-----
>From: boost-docs-bounces <at> lists.boost.org 
>[mailto:boost-docs-bounces <at> lists.boost.org] On Behalf Of David Abrahams
>Sent: 28 April 2008 16:17
>To: boost-docs <at> lists.boost.org
>Subject: Re: [Boost-docs] [stylesheet] forced upcasing of titles

>That said, I think you ought to seriously consider whether small caps
>are an appropriate stylistic thing to enforce globally

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

Agree - indeed I have a violent objection!

Paul

---
Paul A Bristow
Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB
+44 1539561830 & SMS, Mobile +44 7714 330204 & SMS
pbristow <at> hetp.u-net.com
Permalink | Reply |
headers
David Abrahams | 16 May 19:55
Favicon
Gravatar

Re: [stylesheet] forced upcasing of titles


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.
(Continue reading)

Permalink | Reply |

Gmane