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

[ht . lilypond . development]

Another batch of minor comments about the latest version (based somewhat
on an assumption of having a list of supported instead of unsupported
MIDI features in the manual - please just ignore the comments if they do
not make sense the other way around).



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

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2699
Documentation/notation/input.itely:2699:
Supposing that there's a list about features that are supported in MIDI
by default, I think this could already be a good place for presenting it
instead of postponing the list until the section on \articulate.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2708
Documentation/notation/input.itely:2708: A MIDI player that supports
pitch bend will be needed for Microtones.
If this section includes a list of supported features, this information
doesn't need to be repeated as a known issue.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2711
Documentation/notation/input.itely:2711: accent, marcato and portato.
Same here.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2714
Documentation/notation/input.itely:2714: the @code{-dmidi-extension}
option with the @code{lilypond} command:
In the PDF output, this example about changing the default output file
extension gets formatted as if it belonged to the "known issues" list
(which I think is wrong).  A more logical place for these examples would
be after the section on the MIDI block.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2861
Documentation/notation/input.itely:2861: to match any articulations or
tempo indications.  Engraved output
"any articulations or tempo indications" => "some [common] articulations
or tempo change indications"

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2866
Documentation/notation/input.itely:2866: abbreviatures, such as trills
and turns, to be processed as well.
Just tried this: trills and turns work with \articulate even without
\unfoldRepeats, so this explanation about why \unfoldRepeats could be
needed is misleading.

I found in the mailing list archives a comment
<http://lists.gnu.org/archive/html/lilypond-devel/2011-04/msg00068.html>
(by Peter Chubb, the original author of the articulate.ly script) which
asserts that "Articulate doesn't actually need the \unfoldRepeats for
anything.".  Therefore it seems that the use of \unfoldRepeats, even in
the following example, is just the "standard" use which is already
covered in the "Repeats in MIDI" section, so all references to
\unfoldRepeats could possibly be removed from this section.  (Maybe the
linked message's note about the effect of the order of \unfoldRepeats
and \articulate on performance could be given as a "known issue".)

To still give an idea about what the \articulate command can do that is
not supported in MIDI by default, I'd in any case keep the text "the
\articulate command enables abbreviatures, such as trills and turns, to
be processed" and combine it into the previous (and maybe also the next)
paragraph.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2894
Documentation/notation/input.itely:2894: Items that are not reflected in
MIDI output, even with the
In the case that the features supported by default are listed already in
the beginning of the section on MIDI, this list can be removed.

Instead, I think that a warning could be added that the \articulate
function will disable the (new default, issue 3664) effects applied to
articulations (\staccato etc.), so customizing the behavior of
articulations should be done using the variables introduced in the
articulate.ly script.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/input.itely#newcode2951
Documentation/notation/input.itely:2951: See @file{script-init.ly}
A minor problem with adapting the text from the Changes document to this
section on dynamics is that only some of the commands have effects on
MIDI volume.

In the end it's probably easiest to remove the mention about the
articulations from this section (despite some of them having influence
on MIDI volume), and just list the articulations in the list of
supported MIDI features.

What could be useful, however, is a new LilyPond code snippet about
customizing the new default behavior of the articulations, possibly in
the "Enhancing MIDI output" section.

[I have however failed to make one myself...  Firstly, there are no
properties called "midiLength" or "midiExtraVelocity" defined in the
patch [issue 3664] that introduces the new default behavior (there are
references to "midi-length" and "midi-extra-velocity" instead).
Secondly, "script-init.ly" only demonstrates how to (re)define the
commands which produce articulations - as a user I'm wondering whether
this is the only way to customize the behavior, or whether it's possible
to change the ArticulationEvent properties later as seems to be
suggested in the text from the Changes document.  (It certainly doesn't
seem to be as simple as \override ArticulationEvent.midi-extra-velocity
= ... ) ]

https://codereview.appspot.com/120480043/diff/200001/ly/articulate.ly
File ly/articulate.ly (right):

https://codereview.appspot.com/120480043/diff/200001/ly/articulate.ly#newcode32
ly/articulate.ly:32: % Breath marks.
The articulate script does not intepret breath marks: instead, breath
marks are handled by the features introduced in issue 3664.

https://codereview.appspot.com/120480043/diff/200001/ly/articulate.ly#newcode36
ly/articulate.ly:36:
I think the original web page about the Articulate script
<http://nicta.com.au/people/chubbp/articulate> still gives an accurate
basic description of what the \articulate function really does.  I think
this could be very useful information to add (or link) in some form to
the script.  There is some information that could be added or updated,
however:
 * Any note marked staccatissimo is shortened by ac:staccatissimoFactor
(default 1/4)
 * Any note marked tenuto is shortened by ac:tenutoFactor (default 1/1,
so by default notes marked tenuto get their full value).
 * Trills and turns are expanded [...]
   => Trills, turns, mordents and pralls are expanded. [...]

Also, I know that \articulate has been enhanced to do something to grace
notes as well
<http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commit;h=98edd1f29c3b5b488ea41313445a3e6220c4a245>,
but I'm not familiar with the effects of these changes.

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