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

[pkx166h]

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

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.

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