Doc: NR section 3.5.x MIDI file creation tidy up

Doc: NR section 3.5.x MIDI file creation tidy up 

Issue 2877 

This issue is specific to the articulate.ly 
documentation but I feel we're constantly 
updating a 'messy' chapter that doesn't really
follow many of the CG guidelines and could
be better organized. 

So this is an attempt to tidy up. Apart from 
some @cindex or @seealso references no new 
information has been added and nothing 
technical has been removed but some of it
has been moved around so that it is grouped
more logically.

I realise this is a big patch and I did
try to figure out how to make it in smaller
bite-size chunks but it would have been
hard to keep it coherent while undergoing
the change (and is probably why no one has 
really tackled this section to tidy it up).

In the end after some editing I just decided
to carry on a complete the chapter as a whole.

Some snippets have been created from the 
main text as they were inappropriate for the 
NR and the Articulate script now contains 
some additional comments based on previously 
added NR @knownissues that were just a list 
of things that the script didn't support and 
which I felt were better *in* the articulate 
file itself.

The @lilypond examples have been simplified
and turned into @examples instead as the 
engraving output is largely irrelevant 
in a section about MIDI; it also saves a lot
of space.

There is a longer introduction and the sections
have been organized in such a way that it starts
with how to create MIDI files with the default
empty MIDI block, then explains how to use
repeats and multiple voicces in MIDI (again 
still with no MIDI block modifications). 
The next subsection then moves to enhancing
the MIDI output by adding Instruments and then
talks about setting MIDI block properties
finally moving onto the Articulate script.

The last part of the chapter then talks about
Dynamics and Volume - it seemed more sensible
to group those two together and as some of the
volume settings are more complex they are at
the end of the chapter.

[pkx166h, 2014-08-02 21:03:03]

More edits - Patch not yet finalized.

[pkx166h, 2014-08-03 13:37:26]

More tightening up. New snippet added and text taken from 'documentation' and
added directly as comments in the Articulate script

[Trevor Daniels, 2014-08-03 22:06:29]

Looks good James, although the node structure looks rather suspect.  I'm
surprised this built without error.  I've indicated some changes, but these may
not be correct or complete.  Please check this carefully.  The text
reorganisation looks fine though, although I've only read it on Rietveld and may
have missed things.

Trevor

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

https://codereview.appspot.com/120480043/diff/40001/Documentation/notation/in...
Documentation/notation/input.itely:2695: @section Repeats in MIDI
subsection

https://codereview.appspot.com/120480043/diff/40001/Documentation/notation/in...
Documentation/notation/input.itely:2731: Whne using multiple voices, each on one
must @emph{each} contain fully
"When" and delete "on"

https://codereview.appspot.com/120480043/diff/40001/Documentation/notation/in...
Documentation/notation/input.itely:2766: * MIDI Instruments::
The MIDI Instruments node name appeared in a higher menu.
Delete this one.

https://codereview.appspot.com/120480043/diff/40001/Documentation/notation/in...
Documentation/notation/input.itely:2923: @unnumberedsubsubsec MIDI Instruments
subsection

https://codereview.appspot.com/120480043/diff/40001/Documentation/notation/in...
Documentation/notation/input.itely:3021: @section Controlling MIDI dynamics
subsection

[pkx166h, 2014-08-04 05:53:27]

On 2014/08/03 22:06:29, Trevor Daniels wrote:
> Looks good James, although the node structure looks rather suspect.  I'm
> surprised this built without error.  I've indicated some changes, but these
may
> not be correct or complete.  Please check this carefully.  The text
> reorganisation looks fine though, although I've only read it on Rietveld and
may
> have missed things.
> 
> Trevor
> 

Hello Trevor.

The structure is very suspect at the moment and no it doesn't compile :) Hence
the tracker is still 'needs work'. I am using this reitveld to help me see each
change in context of what it was before rather than expecting any serious review
just yet.

My intention was to do this work a bit at a time to make it easier to review (3
or 4 separate patches), but I found that after even a little bit of
re-oragnization, and before I had even begun to try to tighten up the text that
much (as well as simplify the examples) that I was faced with either making
large amounts of changes at once after all or leaving the documentation in a
potentially worse state than it was before in between patches.

I'd done a fair bit of work already, so I kept at it to see where it took me, if
only to understand the chapter as a whole.

As I didn't want to suddenly unleash a completely re-written and re-organized
*whole* chapter and expect devs to review it properly, I thought I would simply
plough on, get to the end and see how it looked. Once I had the complete chapter
re-organized and re-assembled I could then get a much better idea of how I could
really then break it all up into smaller patches after all.

So don't waste any time just yet.

Thanks for noticing though

James

[pkx166h, 2014-08-19 14:40:00]

more tidying up - this now compiles

[pkx166h, 2014-09-07 08:09:41]

Rebase with current master

[pkx166h, 2014-09-27 11:34:14]

compiles doc (thanks Heikki)

[pkx166h, 2014-09-27 11:36:05]

Note, I won't be pushing this through using 'normal' patch countdown time frames
so it gets a proper review.

Thanks for understanding

[marc, 2014-09-27 16:53:21]

Great work! The MIDI stuff is better structured and well explained now – just
one nitpick, see below, otherwise LGTM!

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

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2747: @emph{two} @code{\score} blocks; one
for MIDI (with unfolded repeats)
this is a bit misleading IMHO:

You don't need two \score blocks when using \unfoldRepeats
but you rather need \unfoldRepeats when dealing with both printable output and
MIDI

[ht, 2014-09-27 20:52:40]

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/i...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
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/i...
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/i...
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/i...
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/i...
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/i...
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/i...
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/i...
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/i...
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/i...
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.

[pkx166h, 2014-09-27 21:46:15]

Corrections from Heikki and Marc (thanks)

[pkx166h, 2014-09-27 21:48:15]

Thanks Marc and Heikki.

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

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2656: way for aurally checking music output;
e.g. notes that have been entered
On 2014/09/27 20:52:40, ht wrote:
> 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).

Thanks, I reworded the paragraph.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2658: easy to spot when listening to MIDI
output.
On 2014/09/27 20:52:40, ht wrote:
> Instead of making promises here, I'd write "Listening to MIDI output may help
in
> spotting these errors." (Speaking only from my own experience :-)

Done.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2661: software to extract sound from them.
On 2014/09/27 20:52:40, ht wrote:
> Since MIDI files do not contain sound, is "extract" the correct term?
("Produce"
> could be a possible alternative.)

Done.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2677: @code{\midi} block within the
@code{\score} block;
On 2014/09/27 20:52:40, ht wrote:
> "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.)

Done.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2703: in existing channels being overwritten.
On 2014/09/27 20:52:40, ht wrote:
> 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.

Done.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2747: @emph{two} @code{\score} blocks; one
for MIDI (with unfolded repeats)
On 2014/09/27 16:53:21, marc wrote:
> this is a bit misleading IMHO:
> 
> You don't need two \score blocks when using \unfoldRepeats
> but you rather need \unfoldRepeats when dealing with both printable output and
> MIDI

OK just to confirm the example given (and so hence my misleading wording) is

%%
\score {
  ... music ...
  \layout { }
}
\score {
  \unfoldRepeats {
   ... music ...
  }
  \midi { }
}
%%

But simply writing

%%
\score {
  \unfoldRepeats {
   ... music ...
  }
  \layout { }
  \midi { }
}
%%

is OK? And the 'convention' (of some I suppose) to have two score blocks is to
simply make it easier to separate the notation part of the LilyPond input file
from the MIDI part of the LilyPond input file?

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2781: instruments, @code{\midi} block
properties and/or using the the
On 2014/09/27 20:52:40, ht wrote:
> "using the the" => "using the"

Done.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2866: @cindex context definitions with MIDI
On 2014/09/27 20:52:40, ht wrote:
> 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.

Yes I agree, I have moved this whole section as suggested to the end.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2926: to match any articulations, tempo
indications, dynamic marks etc.
On 2014/09/27 20:52:40, ht wrote:
> 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.)

I've removed the mention of 'dynamics' - stacatto et al is already mentioned in
the @knownissues (it being an 'issue' in that we only support 'simple'
articulations).

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2933: volume linearly between their two
extremes.
On 2014/09/27 20:52:40, ht wrote:
> This paragraph is not specific to the Articulate script; it actually describes
> the behavior of the standard Dynamic_performer.

I moved this para lower down, within but towards the end of the subsection
previously referenced that is now at the end of this section and included an
explicit reference to the Dynamic_performer in internals, just in case it was
not clear.

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:3011: marking.
On 2014/09/27 20:52:40, ht wrote:
> 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.

Yes. Thanks, done.

[marc, 2014-09-28 12:40:00]

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

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2747: @emph{two} @code{\score} blocks; one
for MIDI (with unfolded repeats)
On 2014/09/27 21:48:15, J_lowe wrote:
> On 2014/09/27 16:53:21, marc wrote:
> > this is a bit misleading IMHO:
> > 
> > You don't need two \score blocks when using \unfoldRepeats
> > but you rather need \unfoldRepeats when dealing with both printable output
and
> > MIDI
> 
> OK just to confirm the example given (and so hence my misleading wording) is
> 
> %%
> \score {
>   ... music ...
>   \layout { }
> }
> \score {
>   \unfoldRepeats {
>    ... music ...
>   }
>   \midi { }
> }
> %%
> 
> But simply writing
> 
> %%
> \score {
>   \unfoldRepeats {
>    ... music ...
>   }
>   \layout { }
>   \midi { }
> }
> %%
> 
> is OK? And the 'convention' (of some I suppose) to have two score blocks is to
> simply make it easier to separate the notation part of the LilyPond input file
> from the MIDI part of the LilyPond input file?

I think so. Probably my remarks were misleading, too.

I'd rather rewrite the paragraph to something like:

In order to restrict the effect of @code{\unfoldRepeats} to the MIDI output only
while generating printable scores as well, it is necessary to make @emph{...

I'd read your original text as: "if I want to use \unfoldRepeats, I'll have to
include two \score blocks",
but this is not true – in cases where you need MIDI output only, there is no
need for a second \score.

Sorry for my rather clumsy explanations ...

[pkx166h, 2014-09-29 06:55:03]

Mark H's comment about unfoldrepeats

[pkx166h, 2014-09-29 06:59:01]

Thanks Marc.

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

https://codereview.appspot.com/120480043/diff/100001/Documentation/notation/i...
Documentation/notation/input.itely:2747: @emph{two} @code{\score} blocks; one
for MIDI (with unfolded repeats)
On 2014/09/28 12:40:00, marc wrote:
> On 2014/09/27 21:48:15, J_lowe wrote:
> > On 2014/09/27 16:53:21, marc wrote:
> > > this is a bit misleading IMHO:
> > > 
> > > You don't need two \score blocks when using \unfoldRepeats
> > > but you rather need \unfoldRepeats when dealing with both printable output
> and
> > > MIDI
> > 
> > OK just to confirm the example given (and so hence my misleading wording) is
> > 
> > %%
> > \score {
> >   ... music ...
> >   \layout { }
> > }
> > \score {
> >   \unfoldRepeats {
> >    ... music ...
> >   }
> >   \midi { }
> > }
> > %%
> > 
> > But simply writing
> > 
> > %%
> > \score {
> >   \unfoldRepeats {
> >    ... music ...
> >   }
> >   \layout { }
> >   \midi { }
> > }
> > %%
> > 
> > is OK? And the 'convention' (of some I suppose) to have two score blocks is
to
> > simply make it easier to separate the notation part of the LilyPond input
file
> > from the MIDI part of the LilyPond input file?
> 
> I think so. Probably my remarks were misleading, too.
> 
> I'd rather rewrite the paragraph to something like:
> 
> In order to restrict the effect of @code{\unfoldRepeats} to the MIDI output
only
> while generating printable scores as well, it is necessary to make @emph{...
> 
> I'd read your original text as: "if I want to use \unfoldRepeats, I'll have to
> include two \score blocks",
> but this is not true – in cases where you need MIDI output only, there is no
> need for a second \score.
> 
> Sorry for my rather clumsy explanations ...

Done.

[Valentin Villenave, 2014-10-02 11:19:12]

Greetings James,
I'm far from being the most qualified person to review this, but it looks pretty
good to me.  I'm not sure about the capital A in "the Articulate script" but at
least your patch set is a clear documentation improvement. Cheers!

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

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2654: LilyPond can produce files that conform
to the MIDI (Musical Instrument Digital Interface) standard and so allow for the
checking of the music
Source code formatting: some lines seem a bit long.

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2659: MIDI files do not contain sound like an
MP3 file but require additional
As a matter of consistency, I'd mention a patent-free format alongside mp3 here.

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2689: only produce MIDI output files.  No
notation will be printed.
I'd make this paragraph a @warning{}.

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2784: @q{Articulate} script.
Isn't capitalization redundant with @q{}?

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2888: Only @q{simple} articulations are
supported: staccato, staccatissimo,
Maybe quotes aren't justified here.

[pkx166h, 2014-10-03 07:30:46]

With Valentine's suggestions.

[pkx166h, 2014-10-03 07:32:09]

Thanks Valentine

----

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

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2654: LilyPond can produce files that conform
to the MIDI (Musical Instrument Digital Interface) standard and so allow for the
checking of the music
On 2014/10/02 11:19:12, Valentin Villenave wrote:
> Source code formatting: some lines seem a bit long.

Done.

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2659: MIDI files do not contain sound like an
MP3 file but require additional
On 2014/10/02 11:19:12, Valentin Villenave wrote:
> As a matter of consistency, I'd mention a patent-free format alongside mp3
here.

Done.

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2689: only produce MIDI output files.  No
notation will be printed.
On 2014/10/02 11:19:12, Valentin Villenave wrote:
> I'd make this paragraph a @warning{}.

Done.

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2784: @q{Articulate} script.
On 2014/10/02 11:19:12, Valentin Villenave wrote:
> Isn't capitalization redundant with @q{}?

Well it's called 'Articulate.ly' and the way it is bandied about in the forums,
the term 'Articulate script' seems (to me anyway) like a proper noun. Hence the
capitalization.

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2888: Only @q{simple} articulations are
supported: staccato, staccatissimo,
On 2014/10/02 11:19:12, Valentin Villenave wrote:
> Maybe quotes aren't justified here.

Done.

[dak, 2014-10-03 07:58:40]

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

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2784: @q{Articulate} script.
On 2014/10/03 07:32:09, J_lowe wrote:
> On 2014/10/02 11:19:12, Valentin Villenave wrote:
> > Isn't capitalization redundant with @q{}?
> 
> Well it's called 'Articulate.ly' and the way it is bandied about in the
forums,
> the term 'Articulate script' seems (to me anyway) like a proper noun. Hence
the
> capitalization.

It's not called `Articulate.ly' but most emphatically `articulate.ly', and this
difference is quite significant on case-sensitive file systems.

As a file, @file{articulate.ly} should provide the correct formatting (and
should be used consistently).  The Texinfo description of @file also proposes
using it for buffer names (which tend to be files with missing or added parts)
or "name of a node in Info".  So I'd lean towards "The @file{articulate} script"
in order to skirt the proper name/capitalization issue.  Or just write
@file{articulate.ly} every time, but that seems a bit excessive.

[pkx166h, 2014-10-03 19:27:59]

David K's suggestions

[pkx166h, 2014-10-03 19:29:17]

Thanks.

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

https://codereview.appspot.com/120480043/diff/140001/Documentation/notation/i...
Documentation/notation/input.itely:2784: @q{Articulate} script.
On 2014/10/03 07:58:40, dak wrote:
> On 2014/10/03 07:32:09, J_lowe wrote:
> > On 2014/10/02 11:19:12, Valentin Villenave wrote:
> > > Isn't capitalization redundant with @q{}?
> > 
> > Well it's called 'Articulate.ly' and the way it is bandied about in the
> forums,
> > the term 'Articulate script' seems (to me anyway) like a proper noun. Hence
> the
> > capitalization.
> 
> It's not called `Articulate.ly' but most emphatically `articulate.ly', and
this
> difference is quite significant on case-sensitive file systems.
> 
> As a file, @file{articulate.ly} should provide the correct formatting (and
> should be used consistently).  The Texinfo description of @file also proposes
> using it for buffer names (which tend to be files with missing or added parts)
> or "name of a node in Info".  So I'd lean towards "The @file{articulate}
script"
> in order to skirt the proper name/capitalization issue.  Or just write
> @file{articulate.ly} every time, but that seems a bit excessive.

Done.

[Trevor Daniels, 2014-10-03 21:23:31]

Hi James

This is definitely a big improvement, but I have a serious concern over the
confusion you've introduced about what is supported in basic LilyPond and what
is added by the articulate script.  I've tried to indicate places where this
confusion appears.  The clear statement currently shown in NR 3.5.3 should be
reinstated somehow, and reflected accurately in the text.

Trevor

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
File Documentation/notation/input.itely (left):

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2890: @end itemize
This information seems to have been lost or erroneously moved into the section
on articulate.ly.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2899: @end itemize
Note that these are the only entities modified by articulate.ly.

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

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2702: (#10) for drums.  Each channel is
allocated for each staff, so a score
Staves are assigned to channels in sequence, so a score ...

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2703: that contains more than fifteen staves
will result in the extra staffs
staffs -> staves

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2705: problem if the sharing staffs have
conflicting, channel-based, MIDI
staves

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2872: A full list of supported items can be
found in the script itself.  See
The list you've placed in the script is not correct.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2889: A MIDI player that supports pitch bend
will be needed for Microtones.
This is nothing to do with articulate.ly

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2892: accent, marcato and portato.
These have nothing to do with articulate.ly

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2894: Items that are not supported by the
@file{articulate} script:
Items that are not reflected in MIDI output, even with the @file{articulate}
script.

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

https://codereview.appspot.com/120480043/diff/180001/ly/articulate.ly#newcode46
ly/articulate.ly:46: % Rallentando, accelerando, ritard and 'a tempo'.
This list is misleading.  You've merged the list of items supported in LilyPond
without articulate.ly with the few added by articulate.ly, which are just the
last three.

[ht, 2014-10-04 16:20:51]

Some comments based on looking through the articulate.ly script code (after
having made similar observations about the accuracy of the supported/unsupported
lists as Trevor Daniels did).

Since the default behavior of articulations is about to change in the next
release (issue 3664), I'm worried that this could make it even more difficult to
describe the behavior of articulate.ly accurately, and compare its features with
the new default behavior.

(My preferred choice would in this case to have in the NR enough details about
both the default behavior and the articulate.ly script's features so that the
differences could be understood without going to the source code.  I attempt to
mention some of the details which I consider relevant in my comments.)

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
File Documentation/notation/input.itely (left):

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2890: @end itemize
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> This information seems to have been lost or erroneously moved into the section
> on articulate.ly.

Perhaps the information about what is supported or unsupported in MIDI with or
without the articulate.ly script could be collected from lists into a table?

(This is possibly not a good suggestion, as I don't really see a way to describe
the behavior and differences more accurately than in a list without using a lot
of footnotes, but maybe this idea could be developed further...)

          without \articulate   with \articulate
Pitches        x                      x
Microtones     x                      x
...
Staccato       x (1) (2) (3)          x (2)
Staccatissimo  x (1) (2) (3)          x (2)
Tenuto                                x (2)
Portato        x (2) (3)
Accent         x (1) (3)
Marcato        x (1) (3)
Mordent                               x (4)
Prall                                 x (4)
Trill                                 x (4)
Turn                                  x (4)
...
(1) Volume of articulated notes will be altered.
(2) Duration of articulated notes will be altered.
(3) Only applicable to single notes, not chords.
(4) The pitches cannot be customized.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2899: @end itemize
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> Note that these are the only entities modified by articulate.ly.

I agree.  Looking through the articulate.ly script code, the full list of
articulations and ornaments the script appears to support is
 * staccato,
 * staccatissimo,
 * tenuto,
 * mordent,
 * prall,
 * trill and
 * turn.

Notes with staccato, staccatissimo, or tenuto articulation, and notes without
any articulation, are shortened by customizable factors, unless the notes occur
within slurs or phrasing slurs; mordents, pralls, trills and turns are expanded.
These expansions do not support customizing the pitches to be used, however, so
the expansion may in some cases produce incorrect results; see, for example,
<http://lists.gnu.org/archive/html/lilypond-user/2014-05/msg00399.html>. No
changes are made in MIDI volume.

Tempo changes are implemented by matching text scripts attached to notes against
a hard-coded dictionary of strings ("rit.", "accel.", or "tempo I", for
example).

----

Since 2.18, LilyPond has gained support also for handling some articulations
without \articulate (issue 3664): accent, marcato, staccato, staccatissimo and
portato, together with breath marks (which also shorten notes).

The new default behavior of the articulations is also a bit different from how
the \articulate script would handle them as, without \articulate, both the
length *and* the MIDI volume of the notes may be altered.

The new behavior is (to my understanding) nevertheless disabled in music
processed through \articulate - based on the code review discussion on issue
3664, this appears to be intentional, to not interfere with the old behavior of
\articulate.  However, this means that with the new default behavior of the
articulations, using \articulate on a piece of music may remove some volume
effects.  Also, unlike the \articulate script, which appears to be able to apply
articulations (such as staccato or staccatissimo) to chords as well, the new
default behavior appears to work only for articulations attached to single
notes.

The details about the new, more complex default behavior of articulations (and
how to customize it) are currently described only in the Changes document.  I
believe this information should be available in some form also in the NR as with
further releases, it will become much more difficult to find.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2991: default in the Voice context.  It is
possible to control the overall
This removed sentence reminds me of an issue which, in my opinion, should
deserve a mention at least as a "Known issue" in the NR since I think the fact
that every Voice has its own separate Dynamic_performer by default can be a
source of surprising behavior (especially with temporary voices) where the MIDI
volume does not appear to match what could be expected by looking at the typeset
output.

(This behavior was one of the main reasons that originally led me to study
LilyPond's implementation to understand why the MIDI output volume didn't match
the expectations.  Users still seem to be hit by this issue every now and then
without necessarily being aware of it, see, for example,
<http://lists.gnu.org/archive/html/lilypond-user/2014-05/msg00460.html>.)

Specifically, since
 (1) the introduction of a new Voice also initializes a new 
     Dynamic_performer for MIDI output (which initially has a
     "default" volume), and
 (2) it's the responsibility of the Dynamic_performer to assign a volume
     to each MIDI note,
it follows that the MIDI volume of the notes in the new Voice context will in
effect get "reset" to the new Dynamic_performer's "default" volume level
regardless of any "previous" MIDI volume, unless there's an explicit absolute
dynamic event at the start of the new Voice.

Example:

\score {
  \new Staff {
    \new Voice {
      % ... a long monophonic passage
      c'1\ppppp
      <<
        \new Voice {
          c''2\> % starts at the default velocity, not \ppppp
          g'2\!
        }
        \new Voice {
          c'1    % this note also gets the default velocity
        }
      >>
      % ... continue with a single Voice
    }
  }
  \layout { }
  \midi { }
}

I'd suggest adding the following entry in the "Known issues" list at the end of
the "Setting MIDI volume" subsection:

  Known issue: MIDI dynamics are implemented by the Dynamic_performer,
  which lives by default in the Voice context.  This means that every
  new Voice context, such as one created for a temporary polyphonic
  passage (NR 1.5.2), will have an independent Dynamic_performer 
  initialized with a "default" volume level that will be used for the
  notes in the new voice.  If it is inappropriate to use the default
  volume level for the new voice, make sure to start the voice with an
  explicit dynamic marking, or move the Dynamic_performer from the
  Voice context to the higher-level Staff context.

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

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2898: @item Tempo changes entered as
annotations without tempo markings.
"tempo markings" should possibly be "metronome marks" (NR 1.2.3).

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2901: @item Tremolos entered with
@q{@code{:}[@var{number}]}.
It appears that articulate.ly actually supports also these tremolos (by
unfolding them) since
<http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commit;h=51146a320837b3d...>.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2912: of dynamic markings and the relative
volume of different instruments.
I'd consider moving text from the end of this section to expand the
introduction:

   Dynamic marks translate automatically into volume levels in the available
   MIDI volume range whereas crescendi and decrescendi vary the volume
   linearly between their two extremes.  It is possible to control the relative
   volume of dynamic markings, and the overall volume levels of different
   instruments.

Also, if the goal is to give a complete list about what LilyPond does to MIDI
volume automatically, the new default behavior of some articulations (issue
3664) is relevant also here:

   Also, the articulations \accent, \marcato, \staccatissimo and \staccato
   increase the MIDI volume of the note to which they are attached (in music
   not processed using the articulate.ly script).

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:3108: @rinternals{Dynamic_performer}.
This paragraph can be removed if the information is moved to the beginning of
the subsection about dynamics.

[pkx166h, 2014-10-20 22:40:19]

With Trevor D and HT's suggestions. Thanks.

[pkx166h, 2014-10-20 22:41:16]

Thanks for the input as always.

Still one question remains (see thread below)

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

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2702: (#10) for drums.  Each channel is
allocated for each staff, so a score
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> Staves are assigned to channels in sequence, so a score ...

Done.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2703: that contains more than fifteen staves
will result in the extra staffs
On 2014/10/03 21:23:31, Trevor Daniels wrote:
> staffs -> staves

Done.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2705: problem if the sharing staffs have
conflicting, channel-based, MIDI
On 2014/10/03 21:23:31, Trevor Daniels wrote:
> staves

Done.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2872: A full list of supported items can be
found in the script itself.  See
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> The list you've placed in the script is not correct.

See my response to the comment you made in the script.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2889: A MIDI player that supports pitch bend
will be needed for Microtones.
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> This is nothing to do with articulate.ly

Moved to first @knownissues section.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2892: accent, marcato and portato.
On 2014/10/03 21:23:31, Trevor Daniels wrote:
> These have nothing to do with articulate.ly

Moved to first @knownissues section

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2894: Items that are not supported by the
@file{articulate} script:
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> Items that are not reflected in MIDI output, even with the @file{articulate}
> script.

Done.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2898: @item Tempo changes entered as
annotations without tempo markings.
On 2014/10/04 16:20:50, ht wrote:
> "tempo markings" should possibly be "metronome marks" (NR 1.2.3).

Done.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2901: @item Tremolos entered with
@q{@code{:}[@var{number}]}.
On 2014/10/04 16:20:50, ht wrote:
> It appears that articulate.ly actually supports also these tremolos (by
> unfolding them) since
>
<http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commit;h=51146a320837b3d...>.

Thanks. I have therefore removed this @item.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:2912: of dynamic markings and the relative
volume of different instruments.
On 2014/10/04 16:20:50, ht wrote:
> I'd consider moving text from the end of this section to expand the
> introduction:
> 
>    Dynamic marks translate automatically into volume levels in the available
>    MIDI volume range whereas crescendi and decrescendi vary the volume
>    linearly between their two extremes.  It is possible to control the
relative
>    volume of dynamic markings, and the overall volume levels of different
>    instruments.

Done. This has now been added as you wrote it and that last para at the end of
the section has been removed.

> 
> Also, if the goal is to give a complete list about what LilyPond does to MIDI
> volume automatically, the new default behavior of some articulations (issue
> 3664) is relevant also here:
> 
>    Also, the articulations \accent, \marcato, \staccatissimo and \staccato
>    increase the MIDI volume of the note to which they are attached (in music
>    not processed using the articulate.ly script).

These two last entries are related. 

I've taken the information that was added in the changes.tely when this
enhancement was documented, and added it to the 'Dynamic Marks in MIDI' section
below (with appropriate TexInfo formatting).

Also Trevor Daniels commented about this indirectly in the changes I made to
comments in the articulate.ly script itself. 

So the 'list' of what is supported in LP for MIDI without articulate.ly would
be:

--

% Pitches.
% Microtones.  Needs a MIDI player that supports pitch bends.
% Chords entered as chord names.
% Rhythms entered as note durations, including tuplets.
% Tremolos entered without @q{@code{:}[@var{number}]}.
% Ties.
% Dynamic marks.
% Crescendi, decrescendi over multiple notes.
% Tempo changes entered with a tempo marking.
% Lyrics.
% Simple articulations: staccato, staccatissimo, accent, marcato, and portato.

However, it seems to me that we should be listing what is NOT supported by
LilyPond (or doesn't work [as expected]) rather than what does.

That should be a much easier list to maintain right?

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/i...
Documentation/notation/input.itely:3108: @rinternals{Dynamic_performer}.
On 2014/10/04 16:20:50, ht wrote:
> This paragraph can be removed if the information is moved to the beginning of
> the subsection about dynamics.
> 

Done.

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

https://codereview.appspot.com/120480043/diff/180001/ly/articulate.ly#newcode46
ly/articulate.ly:46: % Rallentando, accelerando, ritard and 'a tempo'.
On 2014/10/03 21:23:31, Trevor Daniels wrote:
> This list is misleading.  You've merged the list of items supported in
LilyPond
> without articulate.ly with the few added by articulate.ly, which are just the
> last three.

Thanks, Heikke also made that same comment - albeit in a different way (i.e. it
was now missing from the main documentation).

See related comment to that as I have a general question regarding this
'supported' list.

[ht, 2014-10-25 12:03:14]

On 2014/10/20 22:41:16, J_lowe wrote:
> So the 'list' of what is supported in LP for MIDI without articulate.ly would
> be:
> 
> --
> 
> % Pitches.
> % Microtones.  Needs a MIDI player that supports pitch bends.
> % Chords entered as chord names.
> % Rhythms entered as note durations, including tuplets.
> % Tremolos entered without @q{@code{:}[@var{number}]}.
> % Ties.
> % Dynamic marks.
> % Crescendi, decrescendi over multiple notes.
> % Tempo changes entered with a tempo marking.

This should probably also be "metronome mark" (NR 1.2.3) to make it clearer that
a numeric tempo indication is needed.

> % Lyrics.
> % Simple articulations: staccato, staccatissimo, accent, marcato, and portato.

Breath marks are missing from this list.

> However, it seems to me that we should be listing what is NOT supported by
> LilyPond (or doesn't work [as expected]) rather than what does.

I think this is a matter of taste.  Even though I don't have very strong opinion
about this, I'd slightly prefer focusing in the documentation on the supported
features, what limitations they have, and how their behavior can be customized,
simply because the set of supported features is more clearly defined by the
implementation.

> That should be a much easier list to maintain right?

Regardless of whether the documentation lists supported or unsupported features,
the list should in any case be checked and updated (if necessary) whenever new
features are added, or existing ones changed, in the future.  I don't think that
maintaining the list is not necessarily going to be definitively easier either
way.

-- 
Heikki Tauriainen

[ht, 2014-10-25 12:09:13]

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/i...
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
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/i...
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/i...
Documentation/notation/input.itely:2711: accent, marcato and portato.
Same here.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
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/i...
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/i...
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/i...
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/i...
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=98edd1f29c3b5b4...>,
but I'm not familiar with the effects of these changes.

[Trevor Daniels, 2014-10-26 22:00:14]

I still have a couple of difficulties with this.  It is very difficult to see
what articulations are represented in basic Midi output and what are not.  Clear
lists are needed, ideally quite early rather than buried in the detail.  And
information about the articulate script should not be placed in the middle of
sections describing basic LilyPond features.  The articulate script is an
optional add-on, and needs to be kept quite separate from the basic LilyPond
facilities and features so users not including the articulate script (probably
most of them) are not confused by it.  Both these changes can be achieved quite
easily and then your patch would be a great improvement!

Trevor

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

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2828: @ref{MIDI instruments}, otherwise Grand
Piano (@code{acoustic grand})
refs should always be placed at the end of a sentence. (See CG 5.4.7)

[pkx166h, 2014-11-23 11:13:11]

Heikki's clarifications

[pkx166h, 2014-11-23 11:24:20]

On 2014/10/26 22:00:14, Trevor Daniels wrote:
> I still have a couple of difficulties with this.  It is very difficult to see
> what articulations are represented in basic Midi output and what are not. 
Clear
> lists are needed, ideally quite early rather than buried in the detail.  And
> information about the articulate script should not be placed in the middle of
> sections describing basic LilyPond features.  The articulate script is an
> optional add-on, and needs to be kept quite separate from the basic LilyPond
> facilities and features so users not including the articulate script (probably
> most of them) are not confused by it.  Both these changes can be achieved
quite
> easily and then your patch would be a great improvement!
> 
> Trevor

Yes I agree. In fact the whole reason for me starting this task and it slightly
getting out of hand in terms of the amount of changes, was because I realised we
needed to re-organize this and unpick the articulate information out of the main
'default MIDI' explanation. The goal with regard to articulate was to inlclude
the 'lists' in the ly file itself (i.e. it is its own documentation).

Heikki has helped improve the distinctions in the last few rounds of patch
reviews (for which I am very grateful), and it seems that we are very nearly
there.

I had attempted to make the articulate script its own section, but ar first it
seemed reasonable to include it as part of the 'improving output' sections - I
expect most users that want to go beyond the basic MIDI are going to use
\articulate before they start to much about with contexts (at least those that
are not easily done and are already documented) so the \articulate command was
in my mind anyway, no different from having functions and variables in the Midi
block itself.

Still I think we could, if desired, lift the whole articulate section out and
move it.  That's not a big deal. But I need those that know more than I to check
that - assume that, for instance, we were going to remove articulate from the NR
completely and what was left only applied to the LP default settings.

If that works here, then we probably just need to move the section somewhere
else within this chapter.

James




> 
>
https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
> File Documentation/notation/input.itely (right):
> 
>
https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
> Documentation/notation/input.itely:2828: @ref{MIDI instruments}, otherwise
Grand
> Piano (@code{acoustic grand})
> refs should always be placed at the end of a sentence. (See CG 5.4.7)

[pkx166h, 2014-11-23 11:24:54]

With Heikki's and Trevor's suggestions

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

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2699: 
On 2014/10/25 12:09:13, ht wrote:
> 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.

Personally I don't see the need for stating what *is* supported (unless I
suppose, that list is significantly larger that what is *not* but it doesn't
seem to be, at least to my uneducated eyes).

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2708: A MIDI player that supports pitch bend
will be needed for Microtones.
On 2014/10/25 12:09:13, ht wrote:
> If this section includes a list of supported features, this information
doesn't
> need to be repeated as a known issue.
See my previous comment.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2711: accent, marcato and portato.
On 2014/10/25 12:09:13, ht wrote:
> Same here.
See my previous comment.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2714: the @code{-dmidi-extension} option with
the @code{lilypond} command:
On 2014/10/25 12:09:13, ht wrote:
> 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.

I have moved it to the end of that MIDI block section. I think it is OK there
and we have enough sections and subsections as it is I think.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2828: @ref{MIDI instruments}, otherwise Grand
Piano (@code{acoustic grand})
On 2014/10/26 22:00:14, Trevor Daniels wrote:
> refs should always be placed at the end of a sentence. (See CG 5.4.7)

Done.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2861: to match any articulations or tempo
indications.  Engraved output
On 2014/10/25 12:09:13, ht wrote:
> "any articulations or tempo indications" => "some [common] articulations or
> tempo change indications"

Done.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2866: abbreviatures, such as trills and
turns, to be processed as well.
On 2014/10/25 12:09:13, ht wrote:
> 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.

Done.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2894: Items that are not reflected in MIDI
output, even with the
On 2014/10/25 12:09:13, ht wrote:
> 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.

See my comments above about listing 'supported vs not supported' features.

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

Thank you, done.

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2951: See @file{script-init.ly}
On 2014/10/25 12:09:13, ht wrote:
> 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.
> 

... hmmm.

I don't want to 'poo poo' a list of supported vs unsupported, it's just my own
personal opinion based on that if you have a list of things that are supposed to
work then by inference everything else does not, so if you miss something or if
you forget something or if you fail to consider something and it doesn't appear
on the list it implies that that 'something' doesn't work which may or may not
be true and extra work is then needed to verify this (is it a bug? doc fix?
regression? enhancement? and so on)

That's my basic philosophy with yes/no lists.

However it is useful to make a distinction between what doesn't work in
\articulate and what doesn't work with default midi output and assume everything
in between does work. But we have to be careful that we don't just end up just
listing bugs or what are, effectively, potential product enhancements either.

We have a few tracker issues like this (\paper function I seem to recall) where
the 'lists' are incomplete of what can and cannot be used and where they can and
cannot be used.

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

Yes that would make sense I think. I did something similar with Clefs in the NR
recently.
> 
> [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 = ...
)
> ]

I suggest to create a new tracker for this so it is not forgotten and can be
added to as needed.

For now, I will remove this para completely and made sure of the reference to
the script-init.ly in the list of 'Installed Files' a few lines down.

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.
On 2014/10/25 12:09:13, ht wrote:
> The articulate script does not intepret breath marks: instead, breath marks
are
> handled by the features introduced in issue 3664.

Removed.

https://codereview.appspot.com/120480043/diff/200001/ly/articulate.ly#newcode36
ly/articulate.ly:36: 
On 2014/10/25 12:09:13, ht wrote:
> 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.

I have added the URL in the comments section.

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

Added a small section of its own for these two - unless you think they deserve
more prominence in the NR proper?

>  * Trills and turns are expanded [...]
>    => Trills, turns, mordents and pralls are expanded. [...]

Updated a para in the main comment above with this information.

> 
> 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=98edd1f29c3b5b4...>,
> but I'm not familiar with the effects of these changes.

If you look at the diff of that commit you will see that these were added in the
articulate.ly file already at the time. So there seems to be nothing more to do
in that regard.

[ht, 2014-12-07 14:22:11]

> On 2014/10/25 12:09:13, ht wrote:
> > 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.
> 
> I have moved it to the end of that MIDI block section. I think it is OK there
> and we have enough sections and subsections as it is I think.

I agree, I didn't mean to suggest that this information should be in a separate
subsection as it just adds more detail to the instructions on how to generate
MIDI output.  Thanks.


As to the inclusion/exclusion of lists of supported/unsupported features:
 
> Personally I don't see the need for stating what *is* supported (unless I
> suppose, that list is significantly larger that what is *not* but it doesn't
> seem to be, at least to my uneducated eyes).
>
> ...
>
> I don't want to 'poo poo' a list of supported vs unsupported, it's just my own
> personal opinion based on that if you have a list of things that are supposed
to
> work then by inference everything else does not, so if you miss something or
if
> you forget something or if you fail to consider something and it doesn't
appear
> on the list it implies that that 'something' doesn't work which may or may not
> be true and extra work is then needed to verify this (is it a bug? doc fix?
> regression? enhancement? and so on)

I think the same argument about the extra work holds for the other direction: by
the same reasoning, everything missing in a list of features that are not
supposed to work can be assumed to be supported, and there's similar extra work
needed to verify whether a failure to handle a particular input construct in
MIDI is just the the result of forgetting to update the list of unsupported MIDI
features if/when LilyPond evolves to handle new notational features.  This is
really a policy issue (which is likely impossible to enforce in this kind of
volunteer project): no new feature contributions should be accepted at all
without the accompanying updates to all the relevant documentation.

Basically I agree that, considered independently, the MIDI section has no need
for lists of supported/unsupported features.  However, because there's a so much
wider variety of musical constructs descibed in the NR which LilyPond supports
in notation but which are ignored when generating MIDI output, I think that
keeping this distinction between notation and MIDI output as clear as possible
in the documentation, as a courtesy for the reader, would still be useful: a
list of (un)supported features would help the reader get a more detailed
overview of what the "default MIDI output [which] is basic" (Section 3.5.3) can
be expected to include.  (Without the details, there's a danger of getting more
questions of the form "I used notational feature X in my score.  However, the
MIDI output is wrong.  What's the problem?" with the stock answer "sorry,
feature X is not supported in MIDI" on the mailing lists.)

> However it is useful to make a distinction between what doesn't work in
> \articulate and what doesn't work with default midi output and assume
everything
> in between does work.

Currently it's not easy to learn about the limitations of default MIDI output
until reaching the section on articulate.ly.  This is what I meant in my
previous review comments about moving the list of (un)supported features already
to Section 3.5.1: to me, this list seems a bit out of place appearing this late
in the documentation (especially if the subsection on articulate.ly is still
going to be moved later in the MIDI section to not mix it with the default MIDI
features).

> We have a few tracker issues like this (\paper function I seem to recall)
where
> the 'lists' are incomplete of what can and cannot be used and where they can
and
> cannot be used.

If there have been bad experiences about maintaining similar lists of
supported/unsupported features, then it's best to remove such lists from the
documentation whenever possible (and it's a perfect time to consider this now
that the MIDI section is being improved).  You certainly have far more
experience about maintaining the documentation than I do: I've expressed my
views about the feature lists just as a user (maybe too) accustomed to all the
details in the old documentation (personally, without the problems in keeping
the lists up-to-date, I would find keeping at least one of the lists more useful
than removing both), but I'll be happy with whatever you decide to do with the
list(s).

>
https://codereview.appspot.com/120480043/diff/200001/ly/articulate.ly#newcode36
> ly/articulate.ly:36: 
> On 2014/10/25 12:09:13, ht wrote:
> > 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.
> 
> I have added the URL in the comments section.
> 
> > 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).
> 
> Added a small section of its own for these two - unless you think they deserve
> more prominence in the NR proper?

No, that's not necessary.  However, I think the above bullet points don't really
deserve so prominent a place even in the articulate.ly script without including
the full list of features here (duplicating information from the referenced web
page).  Duplicating the information from the web page is not necessarily a bad
idea, anyway, so that the information won't get lost even if the page went down
in the future.

> > 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=98edd1f29c3b5b4...>,
> > but I'm not familiar with the effects of these changes.
> 
> If you look at the diff of that commit you will see that these were added in
the
> articulate.ly file already at the time. So there seems to be nothing more to
do
> in that regard.

To me, this commit seems to be the one which adds a new case for handling
GraceMusic in the ac:articulate-chord function defined in the script.  (Prior to
this commit, the script only redefined \afterGrace and \appoggiatura.)  Anyway,
I mentioned this just to make it clear that the additions I suggested don't
cover every new feature that's been added to the script after the referenced web
page was last updated.

[Trevor Daniels, 2014-12-07 23:43:00]

I'm pretty happy with this now.  Just a few relatively minor comments.

Trevor

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

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2677: To create a MIDI output file from a
LilyPond input file, insert an empty
It doesn't have to be empty.  Maybe "insert a @code{\midi} block, usually empty,
within ..."

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

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2683: To create a MIDI output file from a
LilyPond input file, insert an empty
It doesn't have to be empty.  Maybe "insert a @code{\midi} block, usually empty,
within ..."

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2852: @code{channel 10 drum-kits} entries
listed in @file{scm/midi.scm} for
I'm not convinced this is an improvement.  It is unfair to expect
non-programming drummers to (a) locate a file buried deep in the file hierarchy
and (b) understand enough of Scheme to read far enough to find this.  I think
the original wording was more helpful, although I don't mind adding the
reference to the Scheme file with something like, "a full list can be found ...
".  But then you'd need to add a @seealso to LM 4.7.4 Other sources of
information.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2880: turns) to be processed.A full list of
supported items can be found in
2 spaces please

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2881: the script itself.  See
@file{ly/articulate.ly}.
Another @seealso to 4.7.4 Other sources of information.

[ht, 2014-12-14 14:07:24]

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

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2890: @warning{The @file{articulate} script
may shorten chords, which mght not
mght -> might

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2893: and breaths and so could sound worse;
in this case reconfigure the
Technically, possibly a more relevant reason why the output could sound worse is
that the \articulate function will alter the default output even for *notes
without any articulations* (as every note without any articulation will get
"shortened" by ac:normalFactor), and slurs just (temporarily) *disable* this
shortening behavior (so, in fact, the note at which a slur ends is the only note
which \articulate will shorten, at least in the simple case where the slurred
notes don't have any other articulations).

I don't wish all this technical detail to be added here: instead, I'd change the
part added to the previous documentation (after the sentence about shortening
chords) to something like:

    The \articulate function also shortens notes that do not have any
    articulations and so could make them sound worse; to compensate for
    unwanted side effects, restrict the use of the function to shorter
    segments of music, or modify the values of the variables defined in
    the @file{articulate} script to customize the shortening behavior.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2971: the @code{Staff} context.
I'm sorry to still return to this section, but I noticed that the proposed new
organization of the material here could leave some confusion as to how the
different ways of setting the minimum and maximum MIDI volume interact.

I think that it might be clearer (as in the previous documentation) to still
start with describing how to set midiMinimumVolume and midiMaximumVolume on the
Score level, and only then move to tuning the volume ranges on the Staff level
(since Staff-level properties will override any Score-level ones), or using a
custom Score.instrumentEqualizer (which is really an alternative to setting
midiMinimumVolume and midiMaximumVolume – in the Dynamic_performer
implementation, it looks like Score.instrumentEqualizer will not be consulted at
all in a context if either midiMinimumVolume or midiMaximumVolume has been set
in any enclosing context).

This could be achieved by switching the order of the current text (about
Staff.midi{Minimum,Maximum}Volume) and the text about setting the properties at
the Score level (starting at line 3015 below).  In this case also the example
starting at line 2973 is possibly redundant: the example which follows that one
would then "continue" the flute+clarinet example used to demonstrate setting the
context properties on the Score level.

[pkx166h, 2014-12-21 13:55:52]

More suggestions by Trevor and Heikki

[pkx166h, 2014-12-21 13:58:21]

Thanks to Trevor and Heikki.

Issues still to be resolved:

Do we still need to move the articulate section and if so, where?

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

https://codereview.appspot.com/120480043/diff/200001/Documentation/notation/i...
Documentation/notation/input.itely:2677: To create a MIDI output file from a
LilyPond input file, insert an empty
On 2014/12/07 23:43:00, Trevor Daniels wrote:
> It doesn't have to be empty.  Maybe "insert a @code{\midi} block, usually
empty,
> within ..."

Done.

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

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2683: To create a MIDI output file from a
LilyPond input file, insert an empty
On 2014/12/07 23:43:00, Trevor Daniels wrote:
> It doesn't have to be empty.  Maybe "insert a @code{\midi} block, usually
empty,
> within ..."

Done.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2852: @code{channel 10 drum-kits} entries
listed in @file{scm/midi.scm} for
On 2014/12/07 23:43:00, Trevor Daniels wrote:
> I'm not convinced this is an improvement.  It is unfair to expect
> non-programming drummers to (a) locate a file buried deep in the file
hierarchy
> and (b) understand enough of Scheme to read far enough to find this.  I think
> the original wording was more helpful, although I don't mind adding the
> reference to the Scheme file with something like, "a full list can be found
...
> ".  But then you'd need to add a @seealso to LM 4.7.4 Other sources of
> information.

Done.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2880: turns) to be processed.A full list of
supported items can be found in
On 2014/12/07 23:43:00, Trevor Daniels wrote:
> 2 spaces please

Done.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2881: the script itself.  See
@file{ly/articulate.ly}.
On 2014/12/07 23:43:00, Trevor Daniels wrote:
> Another @seealso to 4.7.4 Other sources of information.

Done.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2890: @warning{The @file{articulate} script
may shorten chords, which mght not
On 2014/12/14 14:07:24, ht wrote:
> mght -> might

Done.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2893: and breaths and so could sound worse;
in this case reconfigure the
On 2014/12/14 14:07:24, ht wrote:
> Technically, possibly a more relevant reason why the output could sound worse
is
> that the \articulate function will alter the default output even for *notes
> without any articulations* (as every note without any articulation will get
> "shortened" by ac:normalFactor), and slurs just (temporarily) *disable* this
> shortening behavior (so, in fact, the note at which a slur ends is the only
note
> which \articulate will shorten, at least in the simple case where the slurred
> notes don't have any other articulations).
> 
> I don't wish all this technical detail to be added here: instead, I'd change
the
> part added to the previous documentation (after the sentence about shortening
> chords) to something like:
> 
>     The \articulate function also shortens notes that do not have any
>     articulations and so could make them sound worse; to compensate for
>     unwanted side effects, restrict the use of the function to shorter
>     segments of music, or modify the values of the variables defined in
>     the @file{articulate} script to customize the shortening behavior.

Done.

https://codereview.appspot.com/120480043/diff/220001/Documentation/notation/i...
Documentation/notation/input.itely:2971: the @code{Staff} context.
On 2014/12/14 14:07:24, ht wrote:
> I'm sorry to still return to this section, but I noticed that the proposed new
> organization of the material here could leave some confusion as to how the
> different ways of setting the minimum and maximum MIDI volume interact.
> 
> I think that it might be clearer (as in the previous documentation) to still
> start with describing how to set midiMinimumVolume and midiMaximumVolume on
the
> Score level, and only then move to tuning the volume ranges on the Staff level
> (since Staff-level properties will override any Score-level ones), or using a
> custom Score.instrumentEqualizer (which is really an alternative to setting
> midiMinimumVolume and midiMaximumVolume – in the Dynamic_performer
> implementation, it looks like Score.instrumentEqualizer will not be consulted
at
> all in a context if either midiMinimumVolume or midiMaximumVolume has been set
> in any enclosing context).
> 
> This could be achieved by switching the order of the current text (about
> Staff.midi{Minimum,Maximum}Volume) and the text about setting the properties
at
> the Score level (starting at line 3015 below).  In this case also the example
> starting at line 2973 is possibly redundant: the example which follows that
one
> would then "continue" the flute+clarinet example used to demonstrate setting
the
> context properties on the Score level.

Thanks I've swapped the sections around (I appreciate the time you take to
explain the reasoning). I have left in the 'simple' example though as I think it
is more helpful with both the single and multi-staff examples.

[Trevor Daniels, 2014-12-28 23:40:30]

James

We've now had so many iterations of this I'd lost track of where we were up to
with incremental changes and started over.  I think much of it is improved, but
some basic information has been lost and/or buried.  I've tried to indicate as
clearly (starkly might be more accurate) as possible what should be done to
retrieve it.

Trevor

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

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2674: * Controlling MIDI dynamics::
I would put these in the order:
  The MIDI block
  Controlling MIDI dynamics
  MIDI instruments (taken from Enhancing MIDI output)
  Using repeats with MIDI
  Enhancing MIDI output (just the articulate script)

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2732: accent, marcato and portato.
We need a proper list here showing clearly what is supported, so users new to
midi output can see at the outset what it can do for them.  I asked for this
early in October ("The clear statement currently shown in NR 3.5.3 should be
reinstated somehow, and reflected accurately in the text.") but I don't see it
anywhere yet.  The basic facilities can then be compared with the enhancements
provided by the articulate script to see if that is going to be useful.

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2846: @rinternals{Dynamic_performer}.
I don't think we need this reference here.

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2856: these should be	entered in a
@code{Staff} (not @code{DrumStaff}) context
There seems to be a character that is not a space between "be" and "entered".

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2874: to match many articulation and tempo
indications.  Engraved output
Most articulations are handled by the basic LilyPond performer.  See and use NR
3.5.3.

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2912: @item Chords that are @emph{not}
entered as chord names.
Why is this basic information hidden in the articulate script and what does this
item mean?  Chords entered as notes _are_ supported.  Consider a user who wanted
microtonal chords.  It says earlier microtones need a player that supports them.
 Ok, he says, I have that.  Having tried to make it work for hours he now finds,
buried in a @knownissues in a script he is not using, that microtonal chords are
not supported.  How is that an improvement to the documentation?  What do you
have against the clear lists in NR 3.5.3 presented at the top of the MIDI
section?  Why do you keep trying to suppress it with inaccurate and incomplete
information distributed in several places?

[pkx166h, 2015-03-19 13:34:06]

Rebase with current master (had to recreate new patch manually)

[pkx166h, 2015-04-20 16:30:03]

Trevors comments. Still more work to do with lists

[pkx166h, 2015-04-20 16:31:52]

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

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2674: * Controlling MIDI dynamics::
On 2014/12/28 23:40:30, Trevor Daniels wrote:
> I would put these in the order:
>   The MIDI block
>   Controlling MIDI dynamics
>   MIDI instruments (taken from Enhancing MIDI output)
>   Using repeats with MIDI
>   Enhancing MIDI output (just the articulate script)

Done.

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2732: accent, marcato and portato.
On 2014/12/28 23:40:29, Trevor Daniels wrote:
> We need a proper list here showing clearly what is supported, so users new to
> midi output can see at the outset what it can do for them.  I asked for this
> early in October ("The clear statement currently shown in NR 3.5.3 should be
> reinstated somehow, and reflected accurately in the text.") but I don't see it
> anywhere yet.  The basic facilities can then be compared with the enhancements
> provided by the articulate script to see if that is going to be useful.

See reply to comment for previous RFC at line 2912

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2846: @rinternals{Dynamic_performer}.
On 2014/12/28 23:40:30, Trevor Daniels wrote:
> I don't think we need this reference here.

Done.

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2856: these should be	entered in a
@code{Staff} (not @code{DrumStaff}) context
On 2014/12/28 23:40:30, Trevor Daniels wrote:
> There seems to be a character that is not a space between "be" and "entered".

Done.

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
Documentation/notation/input.itely:2912: @item Chords that are @emph{not}
entered as chord names.
On 2014/12/28 23:40:29, Trevor Daniels wrote:
> Why is this basic information hidden in the articulate script and what does
this
> item mean?  Chords entered as notes _are_ supported.  Consider a user who
wanted
> microtonal chords.  It says earlier microtones need a player that supports
them.
>  Ok, he says, I have that.  Having tried to make it work for hours he now
finds,
> buried in a @knownissues in a script he is not using, that microtonal chords
are
> not supported.  How is that an improvement to the documentation?  What do you
> have against the clear lists in NR 3.5.3 presented at the top of the MIDI
> section?  Why do you keep trying to suppress it with inaccurate and incomplete
> information distributed in several places?

I don't keep trying to suppress anything. As to inaccurate and incomplete, I
think you will find that one had to go hunting to get all the correct
information together in the first place. It was *already* 'inaccurate and
incomplete' before I started this patch.

Not all users use articulate.ly, so the point was to list that what is 'not
supported without articulate.ly' in the section that has nothing to do with
articulate.ly and to list that which 'is supported with the articulate script'
IN the articulate script where *already* seemed to be documenting this kind of
thing in the first place.

What was existing before this patch was a mish-mash of both and what was in the
articulate.ly script seemed to also be severely outdated or needed finer points
made based on recent checkins.

If these lists are all wanted in one place then fine - pick a place - but at
least it has to be clear of which features won't appear in your MIDI output if
you don't use articulate.ly and then that either means you list that all at the
beginning or the end (where we have the articulate script information located).

I was merely following the apparent convention of what worked in articulate was
listed (with all the other previous things before me) in the articulate file
itself. 

Why duplicate that list in two places, as it makes it difficult to maintain does
it not?

Also there seemed to be a 'want' to list what does work which I cannot
understand; as my personal preference for 'lists' like this is that assume it
ALL works unless it is listed that it does not work. Listing things that both do
and don't work again seemed overkill and what if something isn't listed? Does it
work, or doesn't it?

From a cursory look, I felt that saying what worked was simply redundant.

That was all.

I am happy to do whatever the rest wants.

[Trevor Daniels, 2015-04-21 22:06:12]

On 2015/04/20 16:31:52, J_lowe wrote:
> 
>
https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
> Documentation/notation/input.itely:2732: accent, marcato and portato.
> On 2014/12/28 23:40:29, Trevor Daniels wrote:
> > We need a proper list here showing clearly what is supported, so users new
to
> > midi output can see at the outset what it can do for them.  The basic
facilities
> > can then be compared with the enhancements provided by the articulate script
> > to see if that is going to be useful.
> 
> Not all users use articulate.ly, so the point was to list that what is 'not
> supported without articulate.ly' in the section that has nothing to do with
> articulate.ly and to list that which 'is supported with the articulate script'
> IN the articulate script where *already* seemed to be documenting this kind of
> thing in the first place.
> 
> If these lists are all wanted in one place then fine - pick a place - but at
> least it has to be clear of which features won't appear in your MIDI output if
> you don't use articulate.ly and then that either means you list that all at
the
> beginning or the end (where we have the articulate script information
located).
> 
> Also there seemed to be a 'want' to list what does work which I cannot
> understand; as my personal preference for 'lists' like this is that assume it
> ALL works unless it is listed that it does not work. Listing things that both
do
> and don't work again seemed overkill and what if something isn't listed? Does
it
> work, or doesn't it?

This last para seems to be the nub of our disagreement.  I strongly believe
we should list the supported features and you want to list the unsupported
ones.  I should explain why I hold this view.  There are two main reasons:

1. This is a Reference manual.  It is intended to show what LP can do and
how to do it.  That is, it has a positive view: what can be done, not what
cannot be done.  This is apparent from the way the contents list is laid out,
and the way the rest of the document is written, but let me give just a
couple of examples:

a) In 1.1.1 under Note names in other languages it says:
   "The available languages and the note names they define are: "
   and then goes on to list them.  It does not list what languages are not
   supported.

b) In 1.2.1 under Durations it says:
   " Durations as short as 128th notes may be specified. Shorter values are
     possible, but only as beamed notes."  A positive, not a negative statement.

You can find similar lists of what is supported in many other places, and
AFAICS, none that list what is not supported.  Try glancing at the Appendices.

2. MIDI is a complex and extensible standard.  LP, even with articulate.ly,
supports only a fraction of the possibilities.  So it is simply misleading
to let the user believe LP supports everything that is not listed, unless
you are going to have a very long list.  Have a look at
    https://en.wikipedia.org/wiki/MIDI
to see what this would entail.  Look at the range of controllers, sequencers
and synthesizers; look at system exclusive messages and MIDI extensions.

OK, so what am I asking for?  Simply a list of MIDI features supported by
basic LP, and a list of additional features supported when articulate.ly is
included.  That's all.  The two lists exist already.  They're in 3.5.2 under
Supported in MIDI.  The lists need to be updated, but I can do that later.
Where should it go?  As close to the beginning of the MIDI section as is
sensible.  Without your revised section ordering immediately to hand I'll 
have to leave you to decide that.

If you still can't accept this, we'll have to wait until some other developers
chip in with their view.

Other than that, LGTM, and thanks for working so persistently with this!

Trevor

[c_sorensen, 2015-04-21 22:22:04]

On 4/21/15 4:06 PM, "tdanielsmusic@googlemail.com"
<tdanielsmusic@googlemail.com> wrote:

>
>If you still can't accept this, we'll have to wait until some other
>developers
>chip in with their view.

I agree that we should list what is supported, with the idea that anything
not mentioned is not supported.  We should list what is supported by
LilyPond, and then additional items that are supported by LilyPond +
articulate.ly.

Maybe it could be one table, with a column indicating whether it is native
lilypond, or lilypond + articulate.ly.  That way the user wouldn't need to
vist two places to see what is possible.

Thanks,
Carl

[pkx166h, 2015-04-22 07:05:22]

Minor corrections to fix compile errors after previous patch changes

[pkx166h, 2015-05-02 14:24:57]

Added supported and unsupported notation sections. Had to fix a TexInfo Node
conflict since renaming the sections in the last patch. Noticed that gitignore
was preventing me from adding a new snippet because of the file name, although
why it didn't cause me problems in the last 6 or 7 patch runs I have no idea.

[pkx166h, 2015-05-02 14:51:18]

On 2015/04/21 22:06:12, Trevor Daniels wrote:
> On 2015/04/20 16:31:52, J_lowe wrote:
> > 
> >
>
https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/i...
> > Documentation/notation/input.itely:2732: accent, marcato and portato.
> > On 2014/12/28 23:40:29, Trevor Daniels wrote:
> > > We need a proper list here showing clearly what is supported, so users new
> to
> > > midi output can see at the outset what it can do for them.  The basic
> facilities
> > > can then be compared with the enhancements provided by the articulate
script
> > > to see if that is going to be useful.
> > 
> > Not all users use articulate.ly, so the point was to list that what is 'not
> > supported without articulate.ly' in the section that has nothing to do with
> > articulate.ly and to list that which 'is supported with the articulate
script'
> > IN the articulate script where *already* seemed to be documenting this kind
of
> > thing in the first place.
> > 
> > If these lists are all wanted in one place then fine - pick a place - but at
> > least it has to be clear of which features won't appear in your MIDI output
if
> > you don't use articulate.ly and then that either means you list that all at
> the
> > beginning or the end (where we have the articulate script information
> located).
> > 
> > Also there seemed to be a 'want' to list what does work which I cannot
> > understand; as my personal preference for 'lists' like this is that assume
it
> > ALL works unless it is listed that it does not work. Listing things that
both
> do
> > and don't work again seemed overkill and what if something isn't listed?
Does
> it
> > work, or doesn't it?
> 
> This last para seems to be the nub of our disagreement.  I strongly believe
> we should list the supported features and you want to list the unsupported
> ones.  I should explain why I hold this view.  There are two main reasons:
> 
> 1. This is a Reference manual.  It is intended to show what LP can do and
> how to do it.  That is, it has a positive view: what can be done, not what
> cannot be done.  This is apparent from the way the contents list is laid out,
> and the way the rest of the document is written, but let me give just a
> couple of examples:
> 
> a) In 1.1.1 under Note names in other languages it says:
>    "The available languages and the note names they define are: "
>    and then goes on to list them.  It does not list what languages are not
>    supported.
> 
> b) In 1.2.1 under Durations it says:
>    " Durations as short as 128th notes may be specified. Shorter values are
>      possible, but only as beamed notes."  A positive, not a negative
statement.
> 
> You can find similar lists of what is supported in many other places, and
> AFAICS, none that list what is not supported.  Try glancing at the Appendices.
> 
> 2. MIDI is a complex and extensible standard.  LP, even with articulate.ly,
> supports only a fraction of the possibilities.  So it is simply misleading
> to let the user believe LP supports everything that is not listed, unless
> you are going to have a very long list.  Have a look at
>     https://en.wikipedia.org/wiki/MIDI
> to see what this would entail.  Look at the range of controllers, sequencers
> and synthesizers; look at system exclusive messages and MIDI extensions.
> 
> OK, so what am I asking for?  Simply a list of MIDI features supported by
> basic LP, and a list of additional features supported when articulate.ly is
> included.  That's all.  The two lists exist already.  They're in 3.5.2 under
> Supported in MIDI.  The lists need to be updated, but I can do that later.
> Where should it go?  As close to the beginning of the MIDI section as is
> sensible.  Without your revised section ordering immediately to hand I'll 
> have to leave you to decide that.
> 
> If you still can't accept this, we'll have to wait until some other developers
> chip in with their view.
> 
> Other than that, LGTM, and thanks for working so persistently with this!
> 
> Trevor

OK I've made changes to input.itely and articulate.ly. I went back to the
original text and extracted all the lists of things that did and did not work,
then took what was in articulate.ly (that was more useful in the NR than in the
file - but left it in Articulate.ly anyway and added a reference to check the
MIDI section in the NR just so we have things covered.

So it's only those two files that have changed since the last patch.

[Trevor Daniels, 2015-05-02 17:08:23]

Hi James

I'm happy with this now.  Thanks for being so forbearing and persistent in the
face of all the criticism.  So, LGTM!

Trevor

[ht, 2015-05-05 18:58:26]

Hi James,

Just to let you know, for me the changes to the content have been OK already
since patch set 13 - many thanks for this effort!  (Found still one small typo,
though...)

Heikki

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

https://codereview.appspot.com/120480043/diff/320001/Documentation/notation/i...
Documentation/notation/input.itely:2994: @code{\score} block will also also be
reflected in the MIDI output.
"also also" -> "also"

[pkx166h, 2015-05-06 07:01:20]

On 2015/05/05 18:58:26, ht wrote:
> Hi James,
> 
> Just to let you know, for me the changes to the content have been OK already
> since patch set 13 - many thanks for this effort!  (Found still one small
typo,
> though...)
> 
> Heikki
> 
>
https://codereview.appspot.com/120480043/diff/320001/Documentation/notation/i...
> File Documentation/notation/input.itely (right):
> 
>
https://codereview.appspot.com/120480043/diff/320001/Documentation/notation/i...
> Documentation/notation/input.itely:2994: @code{\score} block will also also be
> reflected in the MIDI output.
> "also also" -> "also"

Done.

I won't post another patch for review, unless there are any more corrections
from anyone else before it gets pushed.

Thanks for being patient especially with the hiatus between the last and
previous patches.

[pkx166h, 2017-03-12 18:37:13]

author    James Lowe <pkx166h@gmail.com>   
    Thu, 19 Mar 2015 13:14:19 +0000 (13:14 +0000)
committer    James Lowe <pkx166h@gmail.com>   
    Sun, 10 May 2015 10:58:09 +0000 (11:58 +0100)
commit    [r0129dea8eff59c10ba6e295f6f2cd48083fc5296]

and for the makelsr that is required:

author    James Lowe <pkx166h@gmail.com>   
    Sun, 10 May 2015 11:02:25 +0000 (12:02 +0100)
committer    James Lowe <pkx166h@gmail.com>   
    Sun, 10 May 2015 11:03:49 +0000 (12:03 +0100)
commit    [r2ba2ca2073f389842aa87f85b6c740b8488f0125]