[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation suggestions.
From: |
Peter Toye |
Subject: |
Re: Documentation suggestions. |
Date: |
Tue, 31 Dec 2019 16:53:20 +0000 |
Tuesday, December 31, 2019, 1:28:35 AM, Carl Sorensen wrote:
> 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:
>
> >> 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