Documentation: punctuation in menus

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation: punctuation in menus

Phil Holmes-3
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?

--
Phil Holmes



_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

David Kastrup
"Phil Holmes" <[hidden email]> 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?

--
David Kastrup


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

Phil Holmes
----- Original Message -----
From: "David Kastrup" <[hidden email]>
To: <[hidden email]>
Sent: Tuesday, September 10, 2013 3:37 PM
Subject: Re: Documentation: punctuation in menus


> "Phil Holmes" <[hidden email]> 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?
>
> --
> David Kastrup


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.

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

--
Phil Holmes


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

David Kastrup
"Phil Holmes" <[hidden email]> writes:

> ----- Original Message -----
> From: "David Kastrup" <[hidden email]>
> To: <[hidden email]>
> Sent: Tuesday, September 10, 2013 3:37 PM
> Subject: Re: Documentation: punctuation in menus
>
>
>> "Phil Holmes" <[hidden email]> 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

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

Phil Holmes
----- Original Message -----
From: "David Kastrup" <[hidden email]>
To: "Phil Holmes" <[hidden email]>
Cc: <[hidden email]>
Sent: Tuesday, September 10, 2013 3:58 PM
Subject: Re: Documentation: punctuation in menus


> "Phil Holmes" <[hidden email]> writes:
>
>> ----- Original Message -----
>> From: "David Kastrup" <[hidden email]>
>> To: <[hidden email]>
>> Sent: Tuesday, September 10, 2013 3:37 PM
>> Subject: Re: Documentation: punctuation in menus
>>
>>
>>> "Phil Holmes" <[hidden email]> 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


I understand the issue with colons in node names.  That was why I asked this
question.  I'll ask it again should there be a documentation writer who has
had this to deal with before: what do we use for node names when there is
punctuation (specifically a colon) in a section heading?

--
Phil Holmes


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

David Kastrup
"Phil Holmes" <[hidden email]> writes:

> ----- Original Message -----
> From: "David Kastrup" <[hidden email]>
> To: "Phil Holmes" <[hidden email]>
>>
>> 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.
>
> I understand the issue with colons in node names.  That was why I
> asked this question.  I'll ask it again should there be a
> documentation writer who has had this to deal with before: what do we
> use for node names when there is punctuation (specifically a colon) in
> a section heading?

How about rewording the section heading?

--
David Kastrup

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

Phil Holmes
----- Original Message -----
From: "David Kastrup" <[hidden email]>
To: "Phil Holmes" <[hidden email]>
Cc: <[hidden email]>
Sent: Tuesday, September 10, 2013 4:09 PM
Subject: Re: Documentation: punctuation in menus


> "Phil Holmes" <[hidden email]> writes:
>
>> ----- Original Message -----
>> From: "David Kastrup" <[hidden email]>
>> To: "Phil Holmes" <[hidden email]>
>>>
>>> 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.
>>
>> I understand the issue with colons in node names.  That was why I
>> asked this question.  I'll ask it again should there be a
>> documentation writer who has had this to deal with before: what do we
>> use for node names when there is punctuation (specifically a colon) in
>> a section heading?
>
> How about rewording the section heading?
>
> --
> David Kastrup


I'd prefer to avoid it if possible - there are quite a few and I'm aiming to
make this a purely non-editorial change if possible.  If there's no other
recommended course of action, then clearly I will be forced to do it.

--
Phil Holmes


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

Mark Polesky
In reply to this post by Phil Holmes
Phil Holmes wrote:
> I understand the issue with colons in node names.  That
> was why I asked this question.  I'll ask it again should
> there be a documentation writer who has had this to deal
> with before: what do we use for node names when there is
> punctuation (specifically a colon) in a section heading?

The @node and @subsection don't have to match.  For example,
in Documentation/included/compile.itexi:

  466 @node Saving time with the -j option
  467 @subsection Saving time with the @option{-j} option

I may be wrong, but I think you could just do this:

  @node Warning key signatures and pitches
  @subsection Warning: key signatures and pitches

- Mark

_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel
Reply | Threaded
Open this post in threaded view
|

Re: Documentation: punctuation in menus

Phil Holmes
----- Original Message -----
From: "Mark Polesky" <[hidden email]>
To: "Phil Holmes" <[hidden email]>; "David Kastrup" <[hidden email]>
Cc: <[hidden email]>
Sent: Tuesday, September 10, 2013 5:34 PM
Subject: Re: Documentation: punctuation in menus


Phil Holmes wrote:
> > I understand the issue with colons in node names. That
> > was why I asked this question. I'll ask it again should
> > there be a documentation writer who has had this to deal
> > with before: what do we use for node names when there is
> > punctuation (specifically a colon) in a section heading?

> The @node and @subsection don't have to match. For example,
> in Documentation/included/compile.itexi:
>
> 466 @node Saving time with the -j option
> 467 @subsection Saving time with the @option{-j} option
>
> I may be wrong, but I think you could just do this:
>
> @node Warning key signatures and pitches
> @subsection Warning: key signatures and pitches
>
> - Mark


Thanks Mark (and Trevor).  What I'd not realised, and I now do, is that the
node name (and thus the name in the @menu list) does not have to bear any
resemblance to the heading.  If I get rid of the colon from the node name
and the menu entry, the _actual_ menu text retains the original heading
text.  Thus the following is perfectly allowable:

@menu
* Rubbish::
@end menu

@node Rubbish
@unnumberedsubsubsec Bar lines

I feel an update to the CG coming on.

--
Phil Holmes


_______________________________________________
lilypond-devel mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/lilypond-devel