Documentation suggestions.

[Peter Toye]

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:address@hidden
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:address@hidden
   [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:address@hidden
   2. file:///tmp/www.ptoye.com