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

[pkx166h]

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

https://codereview.appspot.com/120480043/diff/240001/Documentation/notation/input.itely#newcode2674
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/input.itely#newcode2732
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/input.itely#newcode2846
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/input.itely#newcode2856
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/input.itely#newcode2912
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.

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