Re: Commas in section headings

[Trevor Daniels]

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/ref_check.py

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

Trevor



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