Re: Documentation suggestions.

[Peter Toye]

I'm posting this here, as no-one on the devel list has answered, although most 
of the discussion went on in that list.


Peter

=======================================
I've now consolidated the various replies to my original suggestions - sorry 
it's been so long. Unfortunately I spent far too much time fighting VirtualBox 
and Linux without as much success as I'd like. So here are my - fairly small- 
documentation ideas. Sorry I couldn't make formal patches but I'll be far too 
busy with the real world for the next month.

Peter

----------------------------------------

LM 1.2.1 Simple notation. Add a paragraph after the 1st music example:

       Note-names in all examples use the English or Dutch naming system (white 
piano keys are C-B).

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

===8<===========End of original message text===========