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

[tdanielsmusic]

On 2015/04/20 16:31:52, J_lowe wrote:


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


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