Re: Documentation suggestions.

[Peter Toye]

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
>> address@hidden
>> https://lists.gnu.org/mailman/listinfo/bug-lilypond