Re: Documentation suggestions.

[Thomas Morley]

Hi Peter,

many thanks for your suggestions.

Without any intent to offend you, let me (partly) play the devil's
advocate... ;)

Am Mo., 30. Dez. 2019 um 17:11 Uhr schrieb Peter Toye <address@hidden>:
>
> 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.

Well, there _is_ an entry in NR for "language" in
D. LilyPond command index
E. LilyPond index

In the 2.21.0 Docs it's changed to "\language"


> 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"]'

Here I'm confused.
The default note names are dutch.

> 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.'

Can't comment on this, I've never used bar number checks.

> 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.

Here I'm undecided.
For a while I used non-ASCII characters frequently. But menwhile I
went back to use upper- and lower-case alphabetic characters only.
Less cinfusing, imho

Ofcourse, that's not the point...

As long as it is allowed to use non-ASCII characters, it should be documented.
The possibility to use arbitrary signs inside "" should be documented
by all means.

> 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.'

(devil's advokat:)
\keepWithTag and \removeWithTag are music-functions and documented as
such. They return music.
Every music-function checks its argument(s), \keepWithTag needs music
not score like multiple others, e.g. \transpose.
This holds for every music-function (expecting music) and is
documented at least in Extending 2.3.2 Music function usage.

Is there any need to explain this for every music-function expecting music?
Isn't the error-message sufficient?

> 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'.

Well, headers are a complete mess, imho.
We do not only need to differentiate between, header and page-header,
but headers for multiple books of a file, headers for each book of a
file, header for each score and probably even for bookpart as well
(can't remember).
Each level, at least book(part)-level may take its own page-headers,
and footers ...
So your suggestion is likely only a first step.

> 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.

Well, in a certain way it's consensus.
If someone objects, he/she will have some reasoning.
You may want to fight for your patch, i.e. do some convincing work.
This may be a better description/explanation what you aim at. Or you
modify your patch to reflect the comments you've got, etc. Depends on
the objector's reasoning.

In general it's more straight-forward to set up git to submit patches.
Then a formal review happens, including some standard tests.

The bug-list is ok, better use the devel-list, imho.

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

No idea if this could be changed...


Thanks again,
  Harm