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/ _______________________________________________ lilypond-devel mailing list lilypond-devel@gnu.org https://lists.gnu.org/mailman/listinfo/lilypond-devel