Re: Documentation: punctuation in menus

[David Kastrup]

"Phil Holmes" <address@hidden> writes:

> ----- Original Message ----- 
> From: "David Kastrup" <address@hidden>
> To: <address@hidden>
> Sent: Tuesday, September 10, 2013 3:37 PM
> Subject: Re: Documentation: punctuation in menus
>
>
>> "Phil Holmes" <address@hidden> writes:
>>
>>> I'm having a go at
>>> http://code.google.com/p/lilypond/issues/detail?id=3495. Some of the
>>> subsection headings contain punctuation - for example "Warning: key
>>> signatures and pitches" in
>>> http://lilypond.org/doc/v2.17/Documentation/learning/accidentals-and-key-signatures.
>>>  Putting
>>> the colon into a menu entry confuses TexInfo - it thinks it's a
>>> separator.  How do we handle punctuation in headings?
>>
>> Why would you want to make a warning a section of its own and navigate
>> to it via menu?
>
> Because it's our documentation policy.  You'll see from the page that
> it currently is already a subheading - that's against doc policy
> (http://lilypond.org/doc/v2.17/Documentation/contributor/sectioning-commands)
> - so it should be a unnumberedsubsubsec and appear in a menu.

When a policy makes things go from bad to worse, it makes sense to first
change things manually to good before trying to apply policy.  That's a
stupid section title.

> The example I gave was just a single example - there are others.

At any rate, Texinfo is not happy about colons in node names (it doesn't
mind them in section titles as long as there is associated node).  One
can fudge about a bit, but at least the Info backend has no way of
understanding a colon in a node name, and Info is a quite nicely
supported format for the LilyPond docs.

-- 
David Kastrup