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

[ht . lilypond . development]

> 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=98edd1f29c3b5b488ea41313445a3e6220c4a245>,
> > 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.


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