[Top][All Lists]

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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]