Documentation suggestions.

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

Documentation suggestions.

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

Thomas Morley-2
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 <[hidden email]>:

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

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

_______________________________________________
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
-------------------------
Monday, December 30, 2019, 5:29:03 PM, Thomas Morley wrote:

> Hi Peter,

> many thanks for your suggestions.

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

No offence taken :)

> Am Mo., 30. Dez. 2019 um 17:11 Uhr schrieb
> Peter Toye <[hidden email]>:

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

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

I agree with your comment, and it seems that my comment has already been acted upon.


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

I am confused as well! As the documentation is silent, I tried German notation and found that it didn't work so assumed English. Whatever the default, it needs a mention. Replacing "English" with "Dutch" or "Nederlands" (whichever is thought of as better by natives of that country).

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

I got caught with this! Hence my suggestion.

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

Agreed

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

Maybe David has some input?

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


Where?? In NR 3.3.2  \keep(remove)WithTag are described as commands, not functions. There seems to be a category clash here.

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

Surely ordinary users shouldn't be expected to be familiar with the contents of "Extending"? Or are we all extraordinary? Anyway, if a command isn't documented as a function, why should we even look at Extending?

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

It might be, if I had known that \keepWithTag was a function!

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

I've not gone into this very deeply, the only engraving I've done which needed custom page headers used them for the entire document.
I'm not sure they're a complete mess...

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

I'm on a Windows system, which makes it a bit more difficult (as I read the CG). Nor do I know texinfo.

> The bug-list is ok, better use the devel-list, imho.
OK, I'll copy my original to that list too.

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

> No idea if this could be changed...
It's like that semi-porn magazine: Reader's Wives. Just how many wives does the sole reader have?


> Thanks again,
>   Harm

Thanks for all the comments - very useful. We should wait for some more.

Peter
mailto:[hidden email]
www.ptoye.com
_______________________________________________
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.

David Kastrup
In reply to this post by ptoye
Peter Toye <[hidden email]> writes:

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

It isn't.  The default is "nederlands", very much different from
English.

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

Is this a feature of Midi or rather of repeat expansion?

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

Inside of double quotation marks, backslashes and double quotation marks
need to be escaped with backslashes.

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

I think we need to differentiate between what currently works and what
we want to _promote_ as a convention.

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

Music expressions don't need to appear in a \score block.  They can
appear at top level, in a \book, in assignments and other places.

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

It is also called User Guide rather than Users Guide.  It's a guide for
the user, resp. the contributor.  Of course there is more than one such
person, but the singular is pretty common in that kind of context, like
"The Cynic's Guide to Politics".

--
David Kastrup

_______________________________________________
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
Monday, December 30, 2019, 6:39:39 PM, David Kastrup wrote:

> Peter Toye <[hidden email]> writes:

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

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

Thoms Morley has told me that this is in the 2.21 doc.

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

> It isn't.  The default is "nederlands", very much different from
> English.

Sorry - I only tried English and Deutsch. In any case, it needs a mention.

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

> Is this a feature of Midi or rather of repeat expansion?

It seems to be an interaction. Midi doesn't handle repeats (except unfolded) and it seems to mess up the bar number checks if you include Midi output with repeats. Scared me because I thought I couldn't count....

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

> Inside of double quotation marks, backslashes
> and double quotation marks
> need to be escaped with backslashes.

Fine - I'd not tried that, but it's fairly obvious now I think about it that some sort of escape is needed. I suggest adding your sentence to the end of mine.

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

> I think we need to differentiate between what
> currently works and what
> we want to _promote_ as a convention.

To an extent, yes, but a _reference_ manual should be complete, unless there's a positive movement towards changing it in the near future. My suggested text points out the convention, as does LM.

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

> Music expressions don't need to appear in a \score block.  They can
> appear at top level, in a \book, in assignments and other places.

OK. I was wrong in detail. Sorry.

But my basic point is that this isn't mentioned in the documentation as far as I can see. Thomas says that \keepWithTag etc. are music functions, presumably as opposed to commands. I was unaware of this; it doesn't seem to be documented in LM or NR.

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

> It is also called User Guide rather than Users
> Guide.  It's a guide for
> the user, resp. the contributor.  Of course
> there is more than one such
> person, but the singular is pretty common in
> that kind of context, like
> "The Cynic's Guide to Politics".

Maybe I should have added a smiley.


Thanks for all the comments.

Have a good New Year.

Peter
mailto:[hidden email]
www.ptoye.com
_______________________________________________
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.

Trevor Daniels
In reply to this post by ptoye


Peter Toye wrote 30/12/2019 16:11:43
Subject: Documentation suggestions.

>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"]'
Apart from this being wrong (the default being nederlands), the LM 2.1.2
does explain this. See

http://lilypond.org/doc/v2.19/Documentation/learning/pitches-and-key-signatures#pitch-alterations

which says:

"A sharp pitch is made by adding is to the name, and a flat pitch by
adding es. As you might expect, a double sharp or double flat is made by
adding isis or eses. This syntax is derived from note naming conventions
in Nordic and Germanic languages, like German and Dutch. To use other
names for alterations, see Note names in other languages
<http://lilypond.org/doc/v2.19/Documentation/notation/writing-pitches#note-names-in-other-languages>."

In the LM we have tried to introduce the concepts one at a time, and
deliberately avoided mentioning accidentals in Section 1.

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

Carl Sorensen-3
In reply to this post by ptoye


On 12/30/19, 11:58 AM, "Peter Toye" <[hidden email]> wrote:

    Monday, December 30, 2019, 6:39:39 PM, David Kastrup wrote:
   
    > Peter Toye <[hidden email]> writes:
   
    >> 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.
   
 
    >> 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:
   
    > It isn't.  The default is "nederlands", very much different from
    > English.
   
    Sorry - I only tried English and Deutsch. In any case, it needs a mention.

It's mentioned in the Notation Reference, Section 1.1.1 Accidentals, which also has a link to Note Names in other languages.
   
    >> '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"]'

A statement very similar to this is in LM 2.1.2 Accidentals
   
    >> 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.'
   
    > Is this a feature of Midi or rather of repeat expansion?
   
    It seems to be an interaction. Midi doesn't handle repeats (except unfolded) and it seems to mess up the bar number checks if you include Midi output with repeats. Scared me because I thought I couldn't count....

I think that this behavior has been fixed in master: https://sourceforge.net/p/testlilyissues/issues/5624/

So we don't need to add this to the documentation.

   
    >> 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.'
   
    > Inside of double quotation marks, backslashes
    > and double quotation marks
    > need to be escaped with backslashes.
   
    Fine - I'd not tried that, but it's fairly obvious now I think about it that some sort of escape is needed. I suggest adding your sentence to the end of mine.
   
    >> I've changed David's wording slightly to be marginally more accurate
    >> (IMO). This may need to be checked for accuracy.
   
    > I think we need to differentiate between what
    > currently works and what
    > we want to _promote_ as a convention.
   
    To an extent, yes, but a _reference_ manual should be complete, unless there's a positive movement towards changing it in the near future. My suggested text points out the convention, as does LM.

I think we need to be careful about what we write here.  I think in the NR we should have only the recommended usage for variable names in the body text, and put the "Do anything you want with quotes" in the Known Issues section.  That way it will be there, but clearly listed as an exception.
   
    >> 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.'
   
    > Music expressions don't need to appear in a \score block.  They can
    > appear at top level, in a \book, in assignments and other places.
   
    OK. I was wrong in detail. Sorry.
   
    But my basic point is that this isn't mentioned in the documentation as far as I can see. Thomas says that \keepWithTag etc. are music functions, presumably as opposed to commands. I was unaware of this; it doesn't seem to be documented in LM or NR.

LilyPond doesn't have "commands", as far as I can see.  We have music expressions (see LM 2.2.1).  Some music expressions are music functions, which operate on an argument and return music.



    >> 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.
   
    > It is also called User Guide rather than Users
    > Guide.  It's a guide for
    > the user, resp. the contributor.  Of course
    > there is more than one such
    > person, but the singular is pretty common in
    > that kind of context, like
    > "The Cynic's Guide to Politics".
   
    Maybe I should have added a smiley.

It's a legitimate question, but we wrestled with it at the time the Contributor's Guide was created, and decided that the book could be used by any single contributor, so the possessive singular was our choice.

Thanks for your input!

Carl
 

_______________________________________________
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
In reply to this post by Trevor Daniels
Monday, December 30, 2019, 8:33:30 PM, Trevor wrote:




Peter Toye wrote 30/12/2019 16:11:43
Subject: Documentation suggestions.


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"]'
Apart from this being wrong (the default being nederlands), the LM 2.1.2 does explain this. See

http://lilypond.org/doc/v2.19/Documentation/learning/pitches-and-key-signatures#pitch-alterations

which says:

"A sharp pitch is made by adding is to the name, and a flat pitch by adding es. As you might expect, a double sharp or double flat is made by adding isis or eses. This syntax is derived from note naming conventions in Nordic and Germanic languages, like German and Dutch. To use other names for alterations, see Note names in other languages."

In the LM we have tried to introduce the concepts one at a time, and deliberately avoided mentioning accidentals in Section 1.

Trevor


I stand corrected and withdraw my suggestion, except for the comment that the default should be explicitly mentioned. Not everyone speaks musical Dutch :)
_______________________________________________
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
In reply to this post by Carl Sorensen-3
Tuesday, December 31, 2019, 1:28:35 AM, Carl Sorensen wrote:

> On 12/30/19, 11:58 AM, "Peter Toye"
> <[hidden email]> wrote:

>     Monday, December 30, 2019, 6:39:39 PM, David Kastrup wrote:
>    
>     > Peter Toye <[hidden email]> writes:
>    
 

>     >> 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:
>    
>     > It isn't.  The default is "nederlands",
> very much different from
>     > English.
>    
>     Sorry - I only tried English and Deutsch.
> In any case, it needs a mention.

> It's mentioned in the Notation Reference,
> Section 1.1.1 Accidentals, which also has a link
> to Note Names in other languages.
>    
>     >> '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"]'

> A statement very similar to this is in LM 2.1.2 Accidentals

I now agree, but have suggested that the default language be explicitly stated.


>     >> 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.'
>    
>     > Is this a feature of Midi or rather of repeat expansion?
>    
>     It seems to be an interaction. Midi doesn't
> handle repeats (except unfolded) and it seems to
> mess up the bar number checks if you include
> Midi output with repeats. Scared me because I
> thought I couldn't count....

> I think that this behavior has been fixed in
> master:
> https://sourceforge.net/p/testlilyissues/issues/5624/

> So we don't need to add this to the documentation.

Sorry - I didn't know that. Great.

>    
>     >> 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.'
>    
>     > Inside of double quotation marks, backslashes
>     > and double quotation marks
>     > need to be escaped with backslashes.
>    
>     Fine - I'd not tried that, but it's fairly
> obvious now I think about it that some sort of
> escape is needed. I suggest adding your sentence to the end of mine.
>    
>     >> I've changed David's wording slightly to
> be marginally more accurate
>     >> (IMO). This may need to be checked for accuracy.
>    
>     > I think we need to differentiate between what
>     > currently works and what
>     > we want to _promote_ as a convention.
>    
>     To an extent, yes, but a _reference_ manual
> should be complete, unless there's a positive
> movement towards changing it in the near future.
> My suggested text points out the convention, as does LM.

> I think we need to be careful about what we
> write here.  I think in the NR we should have
> only the recommended usage for variable names in
> the body text, and put the "Do anything you want
> with quotes" in the Known Issues section.  That
> way it will be there, but clearly listed as an exception.

That seems very reasonable. Does recommended usage include the non-ASCII characters? It doesn't matter much as long as it's documented somewhere.  Unless this is going to be removed in an imminent release.

Thanks for the idea.

     

>     >> 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.'
>    
>     > Music expressions don't need to appear in a \score block.  They can
>     > appear at top level, in a \book, in assignments and other places.
>    
>     OK. I was wrong in detail. Sorry.
>    
>     But my basic point is that this isn't mentioned in the documentation as far as I can
> see. Thomas says that \keepWithTag etc. are music functions, presumably as opposed to
> commands. I was unaware of this; it doesn't seem to be documented in LM or NR.

> LilyPond doesn't have "commands", as far as I can see.  We have music expressions (see LM
> 2.2.1).  Some music expressions are music functions, which operate on an argument and return music.

Well, I quote from NR:

        The arguments of the \tag, \keepWithTag and \removeWithTag commands

which seems to me to admit that commands do exist.

There seems to be a category issue here - exactly what is a "command", "function", "music expression"? It seems to me that sometimes the terms get mixed up. Granted, a function can return a music expression, so is in some sense in both categories. But many concepts are introduced without saying what they produce. An example is \book. Does this introduce a music expression or a block?   NR 3.1.5 implies the latter, but the term 'block' doesn’t seem to have a formal, or even informal, definition. Only by experimentation did I find out it isn't a music expression. So the naive newbie like myself is left swimming in a sea of partly defined terms.

LM  2.2.1 is more examples than definition, as befits a learning manual.
 
I'm not trying to say that this is a major problem, but it makes learning that much harder; one has to do a lot of experimentation to find out just what is and is not acceptable to the compiler.

> Thanks for your input!

> Carl  

And thank you too. Have a good 2020.

Peter
_______________________________________________
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
In reply to this post by ptoye
I'm posting this here, as no-one on the devel list has answered, although most of the discussion went on in that list.


Peter

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

===8<===========End of original message text===========
_______________________________________________
bug-lilypond mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/bug-lilypond