------------------------- 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 <lilyp...@ptoye.com>: >> 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:lilyp...@ptoye.com >> 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:lilyp...@ptoye.com www.ptoye.com _______________________________________________ bug-lilypond mailing list bug-lilypond@gnu.org https://lists.gnu.org/mailman/listinfo/bug-lilypond