[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation suggestions.
From: |
Peter Toye |
Subject: |
Re: Documentation suggestions. |
Date: |
Mon, 30 Dec 2019 18:29:25 +0000 |
-------------------------
Monday, December 30, 2019, 5:29:03 PM, Thomas Morley wrote:
> Hi Peter,
> many thanks for your suggestions.
> Without any intent to offend you, let me
> (partly) play the devil's
> advocate... ;)
No offence taken :)
> Am Mo., 30. Dez. 2019 um 17:11 Uhr schrieb
> Peter Toye <address@hidden>:
>> 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.
>> I've used the 2.19.83 documentation as the baseline.
>> Have a great 2020.
>> Regards,
>> Peter
>> mailto:address@hidden
>> www.ptoye.com
>> 1. There is no index entry in NR for the \language command. It is mentioned
>> only once: in Section 1.1.1 'Note names in other languages' - I suggest
>> adding an index entry for it.
> Well, there _is_ an entry in NR for "language" in
> D. LilyPond command index
> E. LilyPond index
> In the 2.21.0 Docs it's changed to "\language"
I agree with your comment, and it seems that my comment has already been acted
upon.
>> 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:
>> '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"]'
> Here I'm confused.
> The default note names are dutch.
I am confused as well! As the documentation is silent, I tried German notation
and found that it didn't work so assumed English. Whatever the default, it
needs a mention. Replacing "English" with "Dutch" or "Nederlands" (whichever is
thought of as better by natives of that country).
>> 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.'
> Can't comment on this, I've never used bar number checks.
I got caught with this! Hence my suggestion.
>> 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.'
>> I've changed David's wording slightly to be marginally more accurate (IMO).
>> This may need to be checked for accuracy.
> Here I'm undecided.
> For a while I used non-ASCII characters
> frequently. But menwhile I
> went back to use upper- and lower-case
> alphabetic characters only.
> Less cinfusing, imho
> Ofcourse, that's not the point...
Agreed
> As long as it is allowed to use non-ASCII
> characters, it should be documented.
> The possibility to use arbitrary signs inside "" should be documented
> by all means.
Maybe David has some input?
>> 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.'
> (devil's advokat:)
> \keepWithTag and \removeWithTag are
> music-functions and documented as
> such. They return music.
Where?? In NR 3.3.2 \keep(remove)WithTag are described as commands, not
functions. There seems to be a category clash here.
> Every music-function checks its argument(s),
> \keepWithTag needs music
> not score like multiple others, e.g. \transpose.
> This holds for every music-function (expecting music) and is
> documented at least in Extending 2.3.2 Music function usage.
Surely ordinary users shouldn't be expected to be familiar with the contents of
"Extending"? Or are we all extraordinary? Anyway, if a command isn't documented
as a function, why should we even look at Extending?
> Is there any need to explain this for every
> music-function expecting music?
> Isn't the error-message sufficient?
It might be, if I had known that \keepWithTag was a function!
>> 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'.
> Well, headers are a complete mess, imho.
> We do not only need to differentiate between, header and page-header,
> but headers for multiple books of a file,
> headers for each book of a
> file, header for each score and probably even for bookpart as well
> (can't remember).
> Each level, at least book(part)-level may take its own page-headers,
> and footers ...
> So your suggestion is likely only a first step.
I've not gone into this very deeply, the only engraving I've done which needed
custom page headers used them for the entire document.
I'm not sure they're a complete mess...
>> 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.
> Well, in a certain way it's consensus.
> If someone objects, he/she will have some reasoning.
> You may want to fight for your patch, i.e. do some convincing work.
> This may be a better description/explanation what you aim at. Or you
> modify your patch to reflect the comments
> you've got, etc. Depends on
> the objector's reasoning.
> In general it's more straight-forward to set up git to submit patches.
> Then a formal review happens, including some standard tests.
I'm on a Windows system, which makes it a bit more difficult (as I read the
CG). Nor do I know texinfo.
> The bug-list is ok, better use the devel-list, imho.
OK, I'll copy my original to that list too.
>> Also - should it be "Contributors' Guide". Presumably you have more than one
>> contributor.
> No idea if this could be changed...
It's like that semi-porn magazine: Reader's Wives. Just how many wives does the
sole reader have?
> Thanks again,
> Harm
Thanks for all the comments - very useful. We should wait for some more.
Peter
mailto:address@hidden
www.ptoye.com