Re: IR: Improve performer documentation (issue 6868047)

[src]

David,

On 2012/12/02 11:11:54, dak wrote:

https://codereview.appspot.com/6868047/diff/1/scm/document-translation.scm
> File scm/document-translation.scm (right):

Sorry for resurrecting this a month late, I think I only quite
understood yesterday what you actually meant. It is somewhat obsolete
for this patch, since I have gone on to work on a more complete one (see
<http://code.google.com/p/lilypond/issues/detail?id=3003#c3>), but your
point will be relevant for my new work again, so I guess I better start
defending my case now.


https://codereview.appspot.com/6868047/diff/1/scm/document-translation.scm#newcode21
> scm/document-translation.scm:21: ;; type predicates ly:engraver? and
> ly:performer?.
> I think that this approach is not really helping as it is inflexible
and it
> becomes harder to see "crossovers".  At one point of time, we will
likely get
> translators that are used to output MusicXML, and several translators
can be
> used as either translator or performer (and some, like the autobeamer,
will also
> be used in MusicXML preparation).  So I'd rather make separate
chapters for
> translators used in $defaultlayout (default engravers) and those used
in
> $defaultmidi (default performers), allow for duplicates but mention
when the
> engraver is also being used as performer and vice versa, and make a
separate
> list of translators not used by default (are there any?).

Classifying translators by the output definitions in which they appear
by default is not a good idea in my opinion.

* Translators do not need to belong to any context by default, since
they may implement optional functionality. Yes, there are already some,
for example Ambitus_engraver, Completion_heads_engraver,
Grid_line_span_engraver or Page_turn_engraver.

These still clearly belong to one particular backend; all current
examples to the graphical one, but I see no reason to assume there will
never be optional performers (and, in the future, XML transcribers,
however you will call them) too. I don't think lumping these all
together in a separate category makes any sense.

* Allowing for duplicate translator documentation nodes would not be
logical. Currently this would affect only Timing_translator, but again I
see no reason to assume this will always remain the case.

Each translator is uniquely defined, has a single set of associated
documentation data and, judging from Timing_translator, will work
identically wherever it makes sense to \consist it. Specifically, if a
translator can appear in more than one output definition, it will
operate on a backend-independent level. Then why document it at
backend-specific levels, with duplicated nodes that would have to have
identical text?

[The situation is different for contexts. Layout and MIDI contexts of
the same name have separate definitions with separate docstrings, since
each output definition comes with its own complete context hierarchy.
They are mostly isomorphic, but conceptually this is just a manually
enforced convention to allow you to use the same LilyPond score
definitions for both graphical and MIDI output.

Deviations already exist: GregorianTranscriptionStaff,
GregorianTranscriptionVoice, NoteNames, PetrucciStaff and PetrucciVoice
are defined as layout contexts, but not as MIDI contexts; ChordNameVoice
exists as a MIDI context only. Some of these might actually be
oversights (?), but probably not all.

That it why, in my current personal development version of the Internals
Reference, I have started to document the context hierarchies
separately. You can have a look at the current state at
<http://src.johannesrohrer.de/lilypond/Documentation/internals/contexts.html>.]


My opinion is that you should classify translators based on what they do
(if at all), and looking for where you \consist them by default is not a
reliable way to find this out. The best ones I currently see are still
to either look at a translator's base class (requires new specific type
predicates, which I hesitate to add myself), or at its name. Hence I
stand by my original code.


Best regards, and happy new year to everyone,

Johannes Rohrer

https://codereview.appspot.com/6868047/