lilypond-auto
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Lilypond-auto] Issue 4059 in lilypond: Documentation for issues 360


From: lilypond
Subject: Re: [Lilypond-auto] Issue 4059 in lilypond: Documentation for issues 3601 (based on 3581), 4042 (NR: "MIDI output", Section 3.5)
Date: Wed, 13 Aug 2014 05:51:54 +0000


Comment #3 on issue 4059 by address@hidden: Documentation for issues 3601 (based on 3581), 4042 (NR: "MIDI output", Section 3.5)
http://code.google.com/p/lilypond/issues/detail?id=4059

You raise very good points.  Some comments:

I think we have to mention midiChannelMapping at the very end (or
skip documenting it until we find a use for it, issue 2986)
because midiChannelMapping=#'voice does not work well with with
settings read by the Staff_performer, such as the newly documented
pan, reverb, expression, etc.

Thanks for the links to the existing issues related to this context
property.  Like you said (and what Trevor Daniels also wondered in
issue 2986), with the standard placement of the Staff_performer in
the Staff context there doesn't seem to be a clear use case for
(specifically) the 'voice setting, in which case it would certainly
be easiest to leave the midiChannelMapping context property, or at
least this option, undocumented.  Nevertheless, I think it could be
useful to still mention something about midiChannelMapping in the
NR (at least its 'staff and 'instrument settings) - if not for else,
it would be convenient for understanding the Staff_performer
implementation.

I'm certainly OK with leaving Score.midiChannelMapping undocumented.
What can possibly be still salvaged from the documentation changes I
suggested is the section about the new context properties, with all
references to MIDI channel mappings removed.

The description of other MIDI settings actually becomes longer, not
more concise, if the effect of non-default midiChannelMapping is
described.

Yes, that claim was obviously false.  I was stuck in thinking that
it's somehow necessary to describe the midiChannelMapping context
property, so I thought "if the midiChannelMapping context property,
and how notes will map to MIDI channels for each value of this
property, are described first, then the readers would have all the
necessary information available to be able to understand the
implications of how changing the MIDI channel mapping could affect
the behavior of the MIDI context properties, without having to
explain this separately for every context property in the
documentation".  Obviously, the piece of text I suggested to be
added to the section about Staff.midiInstrument just shows that I
couldn't follow this principle even myself.  Sorry.

I only rarely and briefly have a basic understanding of
midiChannelMappings, yet manage to use MIDI output during my periods
of ignorance.  Heikki, as I think will admit, had no understanding of
midiChannelMappings when implementing the enhancements to MIDI output
now being documented.

I think I originally learned about the existence of the
midiChannelMapping context property when studying the implementation
of Staff_performer to fix problems with dynamic changes not applying
consistently (issue 2707, Rietveld issue 6428075 patch set 1), and
have since used the non-default midiChannelMapping=#'instrument
setting occasionally, before starting to work on the new MIDI related
context properties.  Maybe the problem was that I _knew_ at this point
about the existence of Score.midiChannelMapping, and, knowing that
the new context properties wouldn't probably work very well together
with non-default channel mappings (having similar potential issues
as Staff.midiInstrument), felt a pressure to make up for adding
features which do not work well in all scenarios by, instead of
having the courage to admit this directly, adding technical details
about the channel mappings to "help" readers arrive at this
conclusion by themselves.

----

As to the documentation about MIDI in general, I think that the
MIDI section is a bit special (compared to most other sections of
the Notation Reference) in that it deals with LilyPond's external
interfaces.  Unfortunately, for the documentation writer, this will
raise a question on deciding about the tone in which the material
should be presented - that is, whether the section on MIDI should
be written only as an "introduction to MIDI" for LilyPond users
that have never heard this term before, or whether the
documentation should also serve users who wish to understand the
technical details about how LilyPond translates input to MIDI files,
and how various settings (or their values) used in input files map
to various MIDI concepts.

It could be the case that simply describing the use of the \midi
block, together with information about how to set or change basic
MIDI settings such as instruments and tempo (and possibly volume,
which LilyPond however handles mostly automatically except for
instrument equalization, although even that could be already
considered a more advanced concept), assuming the default
midiChannelMapping ('staff) mode, is likely to be completely
sufficient for LilyPond users who have no previous knowledge about
MIDI, but wish to learn how to output MIDI from LilyPond to be able
to proof-listen their scores.  For this purpose, there is probably
no need to mention even MIDI channels or other "technical" MIDI
terminology.  (The lists of what goes to MIDI and what doesn't -
at least those parts of them which can be explained without using
any technical terms - might also be helpful.)

However, understanding how LilyPond generates MIDI files suddenly
becomes relevant as soon as the default settings fail to produce
the expected output.  For such cases, I think that there should be
a manual which gives also enough technical details about how LilyPond
translates its input to MIDI files (such as the MIDI channel
mapping modes, and the treatment of MIDI volume), to help get a
picture about what could be happening if something doesn't seem to
work as expected, and learn about the possible methods available
to mitigate or work around the issues (without going to the
LilyPond source code as the only resort to learn about things).

Currently, documentation about MIDI can be found only in Section
3.5 of the Notation Reference.  \midi blocks are introduced in the
Learning Manual, too, but that manual mostly just refers to NR 3.5
(with the exception of a "Simulating a fermata in MIDI" snippet in
the section on "Further tweaking").

One possible way which could ease the possible difficulties of
trying to support different types of users at the same time by
providing both "introductory" and technical material in the same
manual would be to move all the introductory material about MIDI
to the Learning Manual, and focus on the full technical level
documentation in the Notation Reference.  (From this viewpoint,
starting the NR's section on MIDI from MIDI channel mappings
could even make some sense.)


--
You received this message because this project is configured to send all issue notifications to this address.
You may adjust your notification preferences at:
https://code.google.com/hosting/settings



reply via email to

[Prev in Thread] Current Thread [Next in Thread]