Re: Doc: NR section 3.5.x MIDI file creation tidy up (issue 120480043 by address@hidden)

[ht . lilypond . development]

Here are some comments on minor details (and some technical details as
well).  The logical flow of the section has improved a lot!



https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2656
Documentation/notation/input.itely:2656: way for aurally checking music
output; e.g. notes that have been entered
More precisely (cf. the previous version of the text), it's not (just)
the MIDI standard, but the possibility to have LilyPond produce files
conforming to this standard, which allows checking the music output
aurally (with the help of an application or device that understands
MIDI).

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2658
Documentation/notation/input.itely:2658: easy to spot when listening to
MIDI output.
Instead of making promises here, I'd write "Listening to MIDI output may
help in spotting these errors." (Speaking only from my own experience
:-)

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2661
Documentation/notation/input.itely:2661: software to extract sound from
them.
Since MIDI files do not contain sound, is "extract" the correct term?
("Produce" could be a possible alternative.)

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2677
Documentation/notation/input.itely:2677: @code{\midi} block within the
@code{\score} block;
"To create simple MIDI output from a LilyPond input file, insert ..."
=> "To create a MIDI output file from a LilyPond input file, insert ..."

(I guess the simplicity of the output depends on the input, unless
"simple" is supposed to refer to the limitations in the MIDI output...
Also, it's important to mention that a file will be output as a result,
as plain "MIDI output" could also mean other things, such as sending
MIDI events directly to a MIDI device.)

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2703
Documentation/notation/input.itely:2703: in existing channels being
overwritten.
The fact that it's channel #10 that is used for drums is a MIDI
technicality (as the user has no direct way of controlling the MIDI
channel allocation except for possibly reordering staves in a score,
assuming the default "channel-per-staff" allocation mode).  It could be
simpler to say that there are 15 MIDI channels available, and one
additional channel for drums.

Also, scores with more than 15 staves will result in some of the staves
*sharing*, but not overwriting, the same MIDI channel.  Whether this is
really a problem depends on whether there are conflicting changes to
channel-based MIDI properties (such as the MIDI instrument) in these
staves.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2781
Documentation/notation/input.itely:2781: instruments, @code{\midi} block
properties and/or using the the
"using the the" => "using the"

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2866
Documentation/notation/input.itely:2866: @cindex context definitions
with MIDI
Up to this point, the flow of material in the MIDI section has been very
logical and easy to follow.  The examples in this subsection however
seem to break this flow by referring to concepts (such as dynamics, and
performers) that haven't been fully introduced.  Of course, this could
well be acceptable - after all, the NR is a reference manual - however,
understanding the examples of this subsection could perhaps be helped
with a description about the various MIDI performers and their purpose
(now that the MIDI section is being improved).

Also, unlike the material presented so far, information about context
modifications and rearrangements may be not as immediately relevant for
"basic" MIDI usage (such as generating MIDI, and changing instruments,
tempo, or dynamics).  Therefore the subsection could possibly be even
moved as "more advanced" material nearer the end of the MIDI section,
after the subsection on MIDI dynamics.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2926
Documentation/notation/input.itely:2926: to match any articulations,
tempo indications, dynamic marks etc.
I think that the Articulate script doesn't concern itself at all with
MIDI dynamics; even when using the script, dynamics are still handled by
LilyPond's standard Dynamic_performer.

However, there's a previous patch by Devon Schudy (issues 3664 and 3740)
which makes some expressive marks (such as staccato) affect MIDI
dynamics when *not* using the \articulate function (this function in
effect removes all such expressive marks from the input, so no MIDI
volume adjustments are made).  (There's documentation about the
improvements in the 2.19 Changes document.)

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode2933
Documentation/notation/input.itely:2933: volume linearly between their
two extremes.
This paragraph is not specific to the Articulate script; it actually
describes the behavior of the standard Dynamic_performer.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/input.itely#newcode3011
Documentation/notation/input.itely:3011: marking.
The new version of the text omits the detail that each of the dynamic
markings corresponds to a fraction of the available volume range.  I
think that it would still be useful to describe the range for the
"internal values", for example, to help understand what the number 0.9
means in the \rfz snippet.

https://codereview.appspot.com/120480043/