Re: Commas in section headings

[Graham Percival]

On Fri, Aug 12, 2011 at 10:22:49PM +0100, Trevor Daniels wrote:
> 
> Graham Percival wrote Friday, August 12, 2011 5:09 PM
> 
> >On Fri, Aug 12, 2011 at 01:41:29PM +0200, Werner LEMBERG wrote:
> >>What I can imagine is that node names get automatically derived
> >>from
> >>section names.  For example, a script might check that,
> >>stripping off
> >>all texinfo commands and other forbidden characters like the
> >>comma.
> >
> > scripts/auxiliar/node-menuify.py
> 
> AFAICS that script simply generates the menus
> from the node names.  It doesn't touch section
> names.

Yes, but I could imagine that script regenerating node names from
section names, then using those new node names to generate the
menus.

> 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?  (for
that matter, why should they know or care that the node name can
differ from the section name?)

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

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

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.

Cheers,
- Graham