Re: Documentation suggestions.

[Carl Sorensen]

On 12/30/19, 11:58 AM, "Peter Toye" <address@hidden> wrote:

    Monday, December 30, 2019, 6:39:39 PM, David Kastrup wrote:
    
    > Peter Toye <address@hidden> 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