Documentation suggestions.

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

Documentation suggestions.

ptoye
I originally sent this to the bug mailing list. Thomas Morley suggests that it would be better on this list.



As an occasional and fairly new Lilypond user I've found that the documentation is occasionally obscure or misleading. I've made a few suggestions below.

I've used the 2.19.83 documentation as the baseline.

Have a great 2020.
 
Regards,

Peter
mailto:[hidden email]
www.ptoye.com

1. There is no index entry in NR for the \language command. It is mentioned only once: in Section 1.1.1 'Note names in other languages' - I suggest adding an index entry for it.

2. Neither LM nor NR mention that the default language for entering pitches is English. This might be confusing to non-English newbie engravers. I suggest adding to LM Section 1.2.1 'Pitches' something like:

'By default, note names are written using English notation. You can change this using the \language command. See [add reference to NR 1.1.1 "Note names in other languages"]'

3. In NR 1.2.5 'Bar and bar number checks' I suggest adding a paragraph at the bottom of the section:

'Note that if MIDI output is selected and volta repeats are in place, the bar number check will fail. It is best to suppress MIDI output whle checking bar numbers.'

4. The characters allowed in variable names are only briefly touched upon: in LR 2.4.1 the use of only alphabetic characters is mentioned as a convention, while NR 3.1.5 states this as a requirement. In a LilyPond-user email David Kastrup said "It's alphabetic characters in the ASCII set plus all non-ASCII characters, potentially interspersed with isolated single underlines or dashes." From other hints and experiments it appears that any characters are allowed if the name is enclosed in double quotation marks. I suggest in NR 3.1.5 'File Structure' in the bullet point 'A variable...' the last sentence is replaced by:

'By convention, the name of a variable consists of upper- and lower-case alphabetic characters only. In addition, non-ASCII characters and non-adjacent single underscores and dashes are also allowed. Any combination of characters is allowed if the variable name is enclosed in double quotation marks.'

I've changed David's wording slightly to be marginally more accurate (IMO). This may need to be checked for accuracy.

5. The context of the various \tag commands is not described. I had assumed that they were lexical items, similar to many directives for conditional compilation; this was not correct! I suggest adding the following text to NR 3.3.2 'Using Tags', but I'm not sure of the best placement. Either close to the top of the section, before the examples, or at the very end, before "see also":

'Note that \keepWithTag and \removeWithTag are themselves music expressions and so must appear within a \score block.'

6. NR Section 3.2 'Titles and Headers" is very confusing: the word "header" is used both for the \header command and for page headers. It is obviously far too late to change the former, so I suggest that where page headers are implied they should be mentioned explicitly. In detail, in NR 3.2.1 and 3.2.2 the sections '...layout of headers and footers' be retitled:

 '...layout of page headers and footers'.

7. Contributor's Guide is a bit confusing. Section 1.2 'Overview of work flow' paragraph 3 says that a contributor's patch needs to be approved for inclusion (usually through the mailing list). But which mailing list? devel, bug or user? And who does the approving? Consensus? I made one suggestion on the user list and got 2 replies, one pro and one against. I can't suggest any concrete text here as I don't (but would like to) know the answer.

Also - should it be "Contributors' Guide". Presumably you have more than one contributor.


===8<===========End of original message text===========
   As an occasional and fairly new Lilypond user I've found that the
   documentation is occasionally obscure or misleading. I've made a few
   suggestions below.
   I've used the 2.19.83 documentation as the baseline.
   Have a great 2020.

   Regards,
   Peter
   [1]mailto:[hidden email]
   [2]www.ptoye.com
   1. There is no index entry in NR for the \language command. It is
   mentioned only once: in Section 1.1.1 'Note names in other languages' -
   I suggest adding an index entry for it.
   2. Neither LM nor NR mention that the default language for entering
   pitches is English. This might be confusing to non-English newbie
   engravers. I suggest adding to LM Section 1.2.1 'Pitches' something
   like:
   'By default, note names are written using English notation. You can
   change this using the \language command. See [add reference to NR 1.1.1
   "Note names in other languages"]'
   3. In NR 1.2.5 'Bar and bar number checks' I suggest adding a paragraph
   at the bottom of the section:
   'Note that if MIDI output is selected and volta repeats are in place,
   the bar number check will fail. It is best to suppress MIDI output whle
   checking bar numbers.'
   4. The characters allowed in variable names are only briefly touched
   upon: in LR 2.4.1 the use of only alphabetic characters is mentioned as
   a convention, while NR 3.1.5 states this as a requirement. In a
   LilyPond-user email David Kastrup said "It's alphabetic characters in
   the ASCII set plus all non-ASCII characters, potentially interspersed
   with isolated single underlines or dashes." From other hints and
   experiments it appears that any characters are allowed if the name is
   enclosed in double quotation marks. I suggest in NR 3.1.5 'File
   Structure' in the bullet point 'A variable...' the last sentence is
   replaced by:
   'By convention, the name of a variable consists of upper- and
   lower-case alphabetic characters only. In addition, non-ASCII
   characters and non-adjacent single underscores and dashes are also
   allowed. Any combination of characters is allowed if the variable name
   is enclosed in double quotation marks.'
   I've changed David's wording slightly to be marginally more accurate
   (IMO). This may need to be checked for accuracy.
   5. The context of the various \tag commands is not described. I had
   assumed that they were lexical items, similar to many directives for
   conditional compilation; this was not correct! I suggest adding the
   following text to NR 3.3.2 'Using Tags', but I'm not sure of the best
   placement. Either close to the top of the section, before the examples,
   or at the very end, before "see also":
   'Note that \keepWithTag and \removeWithTag are themselves music
   expressions and so must appear within a \score block.'
   6. NR Section 3.2 'Titles and Headers" is very confusing: the word
   "header" is used both for the \header command and for page headers. It
   is obviously far too late to change the former, so I suggest that where
   page headers are implied they should be mentioned explicitly. In
   detail, in NR 3.2.1 and 3.2.2 the sections '...layout of headers and
   footers' be retitled:
    '...layout of page headers and footers'.
   7. Contributor's Guide is a bit confusing. Section 1.2 'Overview of
   work flow' paragraph 3 says that a contributor's patch needs to be
   approved for inclusion (usually through the mailing list). But which
   mailing list? devel, bug or user? And who does the approving?
   Consensus? I made one suggestion on the user list and got 2 replies,
   one pro and one against. I can't suggest any concrete text here as I
   don't (but would like to) know the answer.
   Also - should it be "Contributors' Guide". Presumably you have more
   than one contributor.

References

   1. mailto:[hidden email]
   2. file:///tmp/www.ptoye.com
Reply | Threaded
Open this post in threaded view
|

Re: Documentation suggestions.

Kieren MacMillan
Hi Peter (et al.),

> 2. Neither LM nor NR mention that the default language for entering pitches is English.

It is?! When did that change?

If I write

    \version "2.19.83"
    { fis'4 }

it compiles without error. So I think the default is not English.

> 6. NR Section 3.2 'Titles and Headers" is very confusing: the word "header" is used both for the \header command and for page headers. It is obviously far too late to change the former

It’s never too late to improve the Lilypond codebase.  ;)
Indeed, that’s exactly what convert-ly is for.

> Also - should it be "Contributors' Guide". Presumably you have more than one contributor.

It’s fine as is: it’s a guide for you to use if you’re a contributor.
One doesn’t [usually] find a "Users’ Guide", right?

Cheers,
Kieren.


________________________________

Kieren MacMillan, composer (he/him/his)
‣ website: www.kierenmacmillan.info
‣ email: [hidden email]


Reply | Threaded
Open this post in threaded view
|

Re: Documentation suggestions.

ptoye


-------------------------
Tuesday, December 31, 2019, 8:06:06 PM, Kieren MacMillan wrote:

> Hi Peter (et al.),

>> 2. Neither LM nor NR mention that the default language for entering pitches is English.

> It is?! When did that change?

> If I write

>     \version "2.19.83"
>     { fis'4 }

> it compiles without error. So I think the default is not English.

Dealt with in previous emails to the mailing list

>> 6. NR Section 3.2 'Titles and Headers" is very confusing: the word "header" is used both for the \header command and for page headers. It is obviously far too late to change the former

> It’s never too late to improve the Lilypond codebase.  ;)
> Indeed, that’s exactly what convert-ly is for.

But easier I think to change the documentation as I suggested.

>> Also - should it be "Contributors' Guide". Presumably you have more than one contributor.

> It’s fine as is: it’s a guide for you to use if you’re a contributor.
> One doesn’t [usually] find a "Users’ Guide", right?

Sorry - missing smiley :(

Best regards,

Peter
mailto:[hidden email]
www.ptoye.com
Reply | Threaded
Open this post in threaded view
|

Re: Documentation suggestions.

ptoye
I've now consolidated the various replies to my original suggestions - sorry it's been so long. Unfortunately I spent far too much time fighting VirtualBox and Linux without as much success as I'd like. So here are my - fairly small- documentation ideas. Sorry I couldn't make formal patches but I'll be far too busy with the real world for the next month.

Peter

----------------------------------------

LM 1.2.1 Simple notation. Add a paragraph after the 1st music example:

        Note-names in all examples use the English or Dutch naming system (white piano keys are C-B).

LM 2.1.2 Pitches and key signatures. Subsection Pitch alterations. 3rd paragraph
        (1)after 'alterations' add 'and note-names'.
        (2) append:

                The default language for note-names and alterations is nederlands (Dutch).

A question: is "alterations" a good word throughout this subsection? The normal English one is "accidentals", which is used in the Music Glossary reference.
--------------------------------------------
NR 3.1.5 File Structure. Subsection Using variables. Add  a "Known Issues"  subsection at end:


        In addition to the normal convention for variable names [add reference to LM 2.4.1] variable names can include non-ASCII characters and non-adjacent single underscores and dashes. Any combination of characters is allowed if the variable name is enclosed in double quotation marks. In this case backslashes and double quotation marks need to be escaped with backslashes.
-------------------------------------------
NR 1.2.5  Bars. Sub section Bar and bar number checks. Add a "known issues" section at end:

        If MIDI output is selected and volta repeats are in place, the bar number check may fail. It is best to suppress MIDI output whle checking bar numbers.
----------------------------------------------
NR 3.3.2 Different editions from one source. Subsection Using tags. Add before paragraph 3 ("The arguments..."):

        \tag, \keepWithTag and \removeWithTag are music functions which take a music expression as their second argument. Thus they cannot be used to filter items such as  \book or \score blocks.
----------------------------------------------
NR 3.2.1 Creating titles headers and footers. Subsection Default layout of headers and footers. Rename to:

        Default layout of page headers and footers

and index it as "page headers", "page footers", "headers, page", "footers, page".
Possibly also promote it to a 3rd-level section? It doesn't have anything in common with the previous two subsections.
Reply | Threaded
Open this post in threaded view
|

Re: Documentation suggestions.

Michael Käppler-2
Hello Peter,


Am 04.02.2020 um 10:44 schrieb Peter Toye:
> I'm posting this here, as no-one on the devel list has answered, although most of the discussion went on in that list.
I think that many developers spend their effort on core topics like the
guile-2/3 transition,
or improving the contribution process, etc. at the moment.
I prepared a patch, mostly following your suggestions. Now every
developer can discuss your suggestions
during the formal code review procedure.

The review is here:
http://codereview.appspot.com/579280043

The tracker issue is:
https://sourceforge.net/p/testlilyissues/issues/5738/
> LM 1.2.1 Simple notation. Add a paragraph after the 1st music example:
>
>         Note-names in all examples use the English or Dutch naming system (white piano keys are C-B).
As Kieren pointed out it cannot be the English system (at least if
alterations come into play),
I think it is sufficient to mention the Dutch system.
> LM 2.1.2 Pitches and key signatures. Subsection Pitch alterations. 3rd paragraph
>         (1)after 'alterations' add 'and note-names'.
>         (2) append:
>
>                 The default language for note-names and alterations is nederlands (Dutch).
>
> A question: is "alterations" a good word throughout this subsection? The normal English one is "accidentals", which is used in the Music Glossary reference.
IMHO, alteration applys to the underlying process of "altering" a note,
which is part of the input,
"accidental" is the graphical sign that does show the alteration, hence
rather part of the rendering.

> --------------------------------------------
> NR 3.1.5 File Structure. Subsection Using variables. Add  a "Known Issues"  subsection at end:
>
>
>         In addition to the normal convention for variable names [add reference to LM 2.4.1] variable names can include non-ASCII characters and non-adjacent single underscores and dashes. Any combination of characters is allowed if the variable name is enclosed in double quotation marks. In this case backslashes and double quotation marks need to be escaped with backslashes.
> -------------------------------------------
> NR 1.2.5  Bars. Sub section Bar and bar number checks. Add a "known issues" section at end:
>
>         If MIDI output is selected and volta repeats are in place, the bar number check may fail. It is best to suppress MIDI output while checking bar numbers.
> ----------------------------------------------
> NR 3.3.2 Different editions from one source. Subsection Using tags. Add before paragraph 3 ("The arguments..."):
>
>         \tag, \keepWithTag and \removeWithTag are music functions which take a music expression as their second argument. Thus they cannot be used to filter items such as  \book or \score blocks.
> ----------------------------------------------
> NR 3.2.1 Creating titles headers and footers. Subsection Default layout of headers and footers. Rename to:
>
>         Default layout of page headers and footers
>
> and index it as "page headers", "page footers", "headers, page", "footers, page".
> Possibly also promote it to a 3rd-level section? It doesn't have anything in common with the previous two subsections.
Added the indices, but left the title because changing it would have
involved checking and fixing many crossreferences in other
sections / manuals / translations.

Regards and thanks for your work,
Michael
>
> ===8<===========End of original message text===========
> _______________________________________________
> bug-lilypond mailing list
> [hidden email]
> https://lists.gnu.org/mailman/listinfo/bug-lilypond


Reply | Threaded
Open this post in threaded view
|

Re: Documentation suggestions.

ptoye
Dear Michael,

That's very kind of you. When my life gets sorted out I may return to the fray. I've got a few comments below.

I don't have a Reitveld account so can't reply there. Should I get one?

I have another small patch for LR: Section 1.1.4 the first example needs the version number correcting to whatever the next publication references. The other uses of \version are OK.

Best regards,

Peter


-------------------------
Wednesday, February 5, 2020, 1:08:55 PM, you wrote:

> Hello Peter,


> Am 04.02.2020 um 10:44 schrieb Peter Toye:
>> I'm posting this here, as no-one on the devel list has answered, although most of the discussion went on in that list.
> I think that many developers spend their effort on core topics like the
> guile-2/3 transition,
> or improving the contribution process, etc. at the moment.
> I prepared a patch, mostly following your suggestions. Now every
> developer can discuss your suggestions
> during the formal code review procedure.

I thought that too.

> The review is here:
> http://codereview.appspot.com/579280043

> The tracker issue is:
> https://sourceforge.net/p/testlilyissues/issues/5738/
>> LM 1.2.1 Simple notation. Add a paragraph after the 1st music example:
>>
>>         Note-names in all examples use the English or Dutch naming system (white piano keys are C-B).
> As Kieren pointed out it cannot be the English system (at least if
> alterations come into play),
> I think it is sufficient to mention the Dutch system.

I didn't give you a very good patch - I really should have said "Note-names in all examples in this section...". Later sections use alterations/accidentals freely, of course.

I'm slightly worried that new users who aren't Dutch will immediately be put off LilyPond by not understanding the very first real example, or thinking that they have to learn Dutch names for all the musical elements. Users of the Do-Si notation styles may like to know that they can use their native musical language.

>> LM 2.1.2 Pitches and key signatures. Subsection Pitch alterations. 3rd paragraph
>>         (1)after 'alterations' add 'and note-names'.
>>         (2) append:
>>
>>                 The default language for note-names and alterations is nederlands (Dutch).
>>
>> A question: is "alterations" a good word throughout this subsection? The normal English one is "accidentals", which is used in the Music Glossary reference.
> IMHO, alteration applys to the underlying
> process of "altering" a note,
> which is part of the input,
> "accidental" is the graphical sign that does
> show the alteration, hence
> rather part of the rendering.

You don't think it necessary to reference the default? Maybe that should be in

Hmmm. I've never heard the word 'alteration' used in this context. If I refer (in English) to 'F sharp' I call the 'sharp' an accidental, whether it's printed or merely played/heard. 'Alter' can refer to any sort of change, not just semitone pitch adjustments. It might be an ottava sign, for instance. I also note that the corresponding section in NR 1.1.1 is titled 'Accidentals'. We should be consistent here.

I agree that accidentals aren't always alterations - they may be there as a courtesy to the player, or even prefixed to every note whether or not it is necessary.

>> --------------------------------------------
>> NR 3.1.5 File Structure. Subsection Using variables. Add  a "Known Issues"  subsection at end:
>>
>>
>>         In addition to the normal convention for variable names [add reference to LM 2.4.1] variable names can include non-ASCII characters and non-adjacent single underscores and dashes. Any combination of characters is allowed if the variable name is enclosed in double quotation marks. In this case backslashes and double quotation marks need to be escaped with backslashes.

I mostly used David Kastrup's text here. I see that lemzwerg has objected on the grounds that "'Alphabetic characters' and 'non-ASCII characters' are not different sets but are overlapping".. I would point out that LM 2.4.1 uses the term 'alphabetic', presumably meaning [A-Z] and [a-z]. These are all ASCII characters. My text admits the use of single underscores and dashes, lemzwerg's does not. A reference manual shold be complete, while pointing out the difference between best practice (Alpha) and other forms of variable name.

I like the examples he gives, but should point out that 'HornIII' is composed entirely of ASCII characters. Maybe more useful than the made-up Greek would be a real example- try 'Теноры'

>> -------------------------------------------
>> NR 1.2.5  Bars. Sub section Bar and bar number checks. Add a "known issues" section at end:
>>
>>         If MIDI output is selected and volta repeats are in place, the bar number check may fail. It is best to suppress MIDI output while checking bar numbers.

I see that Dan Eble has objected to this on the grounds that bar number checking is suppressed during MIDI output. Not in my version (2.19.83)! That's how I discovered the issue and thought that I couldn't count. Maybe it's a later patch. Either way, it needs documentation here, or people will get the wrong bar numbers by accident.

>> ----------------------------------------------
>> NR 3.3.2 Different editions from one source. Subsection Using tags. Add before paragraph 3 ("The arguments..."):
>>
>>         \tag, \keepWithTag and \removeWithTag are music functions which take a music expression as their second argument. Thus they cannot be used to filter items such as  \book or \score blocks.

I'd suggest removing 'All' from the start of your rewritten patch; it doesn't add anything to the meaning. I'd say "Men cannot live forever" rather than "All men cannot live forever". But "All people must die" is OK (as a fact), has a slightly different meaning from than "People must die" (which might be a command to an assassination squad). Not quite sure why - it's style as much as anything else and I can't put my finger on it. Maybe it's the negative, as 'All men are mortal' is fine.

I stll prefer my original wording as it explains why the restriction exists - there was some discusison about how I'd got it wrong. I'm not happy now about the use of the word 'command' if, as I was told, there's no such concept in Lilypond. See Carl Sorenson's comment in http://lilypond.1069038.n5.nabble.com/Documentation-suggestions-tc226575.html#none But I don't know enough to produce a good patch here.

>> ----------------------------------------------
>> NR 3.2.1 Creating titles headers and footers. Subsection Default layout of headers and footers. Rename to:
>>
>>         Default layout of page headers and footers
>>
>> and index it as "page headers", "page footers", "headers, page", "footers, page".
>> Possibly also promote it to a 3rd-level section? It doesn't have anything in common with the previous two subsections.
> Added the indices, but left the title because changing it would have
> involved checking and fixing many
> crossreferences in other
> sections / manuals / translations.

I had assumed cross-refs would be automatic. A shame.

> Regards and thanks for your work,
> Michael
>>
>> ===8<===========End of original message text===========
>> _______________________________________________
>> bug-lilypond mailing list
>> [hidden email]
>> https://lists.gnu.org/mailman/listinfo/bug-lilypond
Reply | Threaded
Open this post in threaded view
|

Re: Documentation suggestions.

Michael Käppler-2
Dear Peter,
it would be nice if you could register yourself at Rietveld. If you
already have a Google account it should be
straightforward, I think.
Please see the updated issue at:
https://codereview.appspot.com/579280043/

>
> I didn't give you a very good patch - I really should have said
> "Note-names in all examples in this section...". Later sections use
> alterations/accidentals freely, of course.
>
> I'm slightly worried that new users who aren't Dutch will immediately
> be put off LilyPond by not understanding the very first real example,
> or thinking that they have to learn Dutch names for all the musical
> elements. Users of the Do-Si notation styles may like to know that
> they can use their native musical language.
Ok, changed this.

>
> >> LM 2.1.2 Pitches and key signatures. Subsection Pitch alterations.
> 3rd paragraph
> >>         (1)after 'alterations' add 'and note-names'.
> >>         (2) append:
> >>
> >>                 The default language for note-names and alterations
> is nederlands (Dutch).
> >>
> >> A question: is "alterations" a good word throughout this
> subsection? The normal English one is "accidentals", which is used in
> the Music Glossary reference.
> > IMHO, alteration applys to the underlying
> > process of "altering" a note,
> > which is part of the input,
> > "accidental" is the graphical sign that does
> > show the alteration, hence
> > rather part of the rendering.
>
> You don't think it necessary to reference the default? Maybe that
> should be in
Seems a bit redundant to me. Adjusted it, nevertheless.
>
> Hmmm. I've never heard the word 'alteration' used in this context. If
> I refer (in English) to 'F sharp' I call the 'sharp' an accidental,
> whether it's printed or merely played/heard. 'Alter' can refer to any
> sort of change, not just semitone pitch adjustments. It might be an
> ottava sign, for instance. I also note that the corresponding section
> in NR 1.1.1 is titled 'Accidentals'. We should be consistent here.
Ok, Done.

>
> I agree that accidentals aren't always alterations - they may be there
> as a courtesy to the player, or even prefixed to every note whether or
> not it is necessary.
>
> >> --------------------------------------------
> >> NR 3.1.5 File Structure. Subsection Using variables. Add  a "Known
> Issues"  subsection at end:
> >>
> >>
> >>         In addition to the normal convention for variable names
> [add reference to LM 2.4.1] variable names can include non-ASCII
> characters and non-adjacent single underscores and dashes. Any
> combination of characters is allowed if the variable name is enclosed
> in double quotation marks. In this case backslashes and double
> quotation marks need to be escaped with backslashes.
>
> I mostly used David Kastrup's text here. I see that lemzwerg has
> objected on the grounds that "'Alphabetic characters' and 'non-ASCII
> characters' are not different sets but are overlapping".. I would
> point out that LM 2.4.1 uses the term 'alphabetic', presumably meaning
> [A-Z] and [a-z]. These are all ASCII characters. My text admits the
> use of single underscores and dashes, lemzwerg's does not. A reference
> manual shold be complete, while pointing out the difference between
> best practice (Alpha) and other forms of variable name.
>
> I like the examples he gives, but should point out that 'HornIII' is
> composed entirely of ASCII characters. Maybe more useful than the
> made-up Greek would be a real example- try 'Теноры'
I tried to combine Werner's and your approach.

>
> >> -------------------------------------------
> >> NR 1.2.5  Bars. Sub section Bar and bar number checks. Add a "known
> issues" section at end:
> >>
> >>         If MIDI output is selected and volta repeats are in place,
> the bar number check may fail. It is best to suppress MIDI output
> while checking bar numbers.
>
> I see that Dan Eble has objected to this on the grounds that bar
> number checking is suppressed during MIDI output. Not in my version
> (2.19.83)! That's how I discovered the issue and thought that I
> couldn't count. Maybe it's a later patch. Either way, it needs
> documentation here, or people will get the wrong bar numbers by accident.
It is fixed in master. The documentation that we are working on must be
valid for current master, not for older versions.
Removed it, thus.

>
> >> ----------------------------------------------
> >> NR 3.3.2 Different editions from one source. Subsection Using tags.
> Add before paragraph 3 ("The arguments..."):
> >>
> >>         \tag, \keepWithTag and \removeWithTag are music functions
> which take a music expression as their second argument. Thus they
> cannot be used to filter items such as  \book or \score blocks.
>
> I'd suggest removing 'All' from the start of your rewritten patch; it
> doesn't add anything to the meaning. I'd say "Men cannot live forever"
> rather than "All men cannot live forever". But "All people must die"
> is OK (as a fact), has a slightly different meaning from than "People
> must die" (which might be a command to an assassination squad). Not
> quite sure why - it's style as much as anything else and I can't put
> my finger on it. Maybe it's the negative, as 'All men are mortal' is fine.
>
> I stll prefer my original wording as it explains why the restriction
> exists - there was some discusison about how I'd got it wrong. I'm not
> happy now about the use of the word 'command' if, as I was told,
> there's no such concept in Lilypond. See Carl Sorenson's comment in
> http://lilypond.1069038.n5.nabble.com/Documentation-suggestions-tc226575.html#none But
> I don't know enough to produce a good patch here.
The NR already uses the word 'command' in the same paragraph. I changed
it a little bit to incorporate the 'restriction cause'.

>
> >> ----------------------------------------------
> >> NR 3.2.1 Creating titles headers and footers. Subsection Default
> layout of headers and footers. Rename to:
> >>
> >>         Default layout of page headers and footers
> >>
> >> and index it as "page headers", "page footers", "headers, page",
> "footers, page".
> >> Possibly also promote it to a 3rd-level section? It doesn't have
> anything in common with the previous two subsections.
> > Added the indices, but left the title because changing it would have
> > involved checking and fixing many
> > crossreferences in other
> > sections / manuals / translations.
>
> I had assumed cross-refs would be automatic. A shame.
IIUC the references are automatic, but if you change the name of a node
you have to adjust
the names in the reference commands, too, how else should Texinfo find
the corresponding section..
At least this is my understanding, I'm happy with being corrected..

Regards,
Michael
Reply | Threaded
Open this post in threaded view
|

Re: Documentation suggestions.

Jean-Charles Malahieude-2
Le 05/02/2020 à 23:30, Michael Käppler a écrit :
> Dear Peter,
> it would be nice if you could register yourself at Rietveld. If you
> already have a Google account it should be
> straightforward, I think.
> Please see the updated issue at:
> https://codereview.appspot.com/579280043/
>

You don't need a Google account. Just give a valid email address.