[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Commas in section headings

From: Trevor Daniels
Subject: Re: Commas in section headings
Date: Fri, 12 Aug 2011 23:09:45 +0100

Graham Percival wrote Friday, August 12, 2011 10:44 PM

On Fri, Aug 12, 2011 at 10:22:49PM +0100, Trevor Daniels wrote:

Graham Percival wrote Friday, August 12, 2011 5:09 PM

I don't see what difficulties arise from having
section names that differ slightly from the node
name, other than maybe a doc editor looking at
the section name rather than the node name when
writing a cross-reference.

Because some new doc editor -- quite possibly with relatively poor
English skills -- will write something new and @ref{} the section
name they see in the HMTL docs.  Why would they bother checking
for an obscure rule about removing commas in the node name?

In that case I'll not bother adding an obscure
rule to the CG about removing commas in section
names.  Why would anyone bother reading it?

This would soon be picked up as a broken ref.

How often do people check for those?  (a broken @rlearning{}, say,
rather than a broken @ref{})
I think I've done it 3 or 4 times in the past eight years.  I'd be
surprised if James knows what we're talking about.

I check all the English docs every time I edit
a file.  It's in my script.  I'd expect every
doc editor to use it.

See scripts/auxiliar/

This found the broken ref that started this discussion
when I checked one of James' recent (unrelated) patches.

(It wasn't broken because of the commas, it was
because James/Mark had changed the node and
section names without changing the ref.)

Unless there's a sound reason for this restriction
I'd rather go back to permitting commas in section

It adds extra confusion for casual doc editors, and I don't think
we should be making it harder for contributors.  Besides, it's not
hard to describe a section without using commas.

What would you suggest for
 Creating titles, headers, and footers
 Custom headers, footers, and titles

I really don't see a good confusion-vs-niceness ratio for the use
of commas in section names.  Making a new section name is much
less rare than adding a reference, so let's keep the "confusion"
isolated to that case.

Well, I disagree (not for the first time)
but you're the boss :)

(BTW, I believe there are commas in some of the
other language docs.)


No virus found in this message.
Checked by AVG -
Version: 10.0.1392 / Virus Database: 1520/3829 - Release Date: 08/12/11

reply via email to

[Prev in Thread] Current Thread [Next in Thread]