Re: Commas in section headings

[Graham Percival]

On Fri, Aug 12, 2011 at 11:09:45PM +0100, Trevor Daniels wrote:
> 
> Graham Percival wrote Friday, August 12, 2011 10:44 PM
> 
> >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.

ok, I've done it.

> Why would anyone bother reading it?

They won't, until we reject their patch and tell them to read the
CG.  ok, that's not entirely true; about 10% - 20% of doc-writers
read the CG before sending patches.  But the vast majority don't
catch on until they've had patches rejected a couple of times.


> 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

- how do I run this?  Could you add
#!/usr/bin/env python
to the top?

- could you change it to use 4-space indents, as now specified by
  GOP-PROP 1 ?

> >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'd have separate sections for
  Creating titles
  Creating headers and footers
  Custom @code{\header} material
but I'm not married to that idea.

> >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 :)

At this point I'll just go with my boss-dom and put my foot down.

I'll leave the door open in a few ways:
- we can certainly re-evaluate this if we had an automatic script
  to generate @node.  (which we should have anyway)
- we can have a longer discussion about documentation policy
  issues once more important GOP stuff has been handled (say, in 4
  or 5 months)
- I've been wanting to have somebody else become Documentation
  Meister for the past 3 years.
  (that said, I'm getting really fed up with all the questions
  about vocal music, and I'm also sick of all the urgent technical
  stuff that breaks, so I'm starting to have an itch to spend a
  weekend to completely rewrite docs about lyrics.  So maybe I'm
  not completely over being Doc Meister after all)

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

The fact that other language docs are broken in places is hardly a
surprise.  :)

Cheers,
- Graham