Re: Documentation suggestions.

[Michael Käppler]

Dear Peter,
it would be nice if you could register yourself at Rietveld. If you
already have a Google account it should be
straightforward, I think.
Please see the updated issue at:
https://codereview.appspot.com/579280043/

> 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.
Ok, changed this.
> >> 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
Seems a bit redundant to me. Adjusted it, nevertheless.
> 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.
Ok, Done.
> 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 'Теноры'
I tried to combine Werner's and your approach.
> >> -------------------------------------------
> >> 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.
It is fixed in master. The documentation that we are working on must be
valid for current master, not for older versions.
Removed it, thus.

> >> ----------------------------------------------
> >> 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.
The NR already uses the word 'command' in the same paragraph. I changed
it a little bit to incorporate the 'restriction cause'.
> >> ----------------------------------------------
> >> 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.
IIUC the references are automatic, but if you change the name of a node
you have to adjust
the names in the reference commands, too, how else should Texinfo find
the corresponding section..
At least this is my understanding, I'm happy with being corrected..

Regards,
Michael