IR: Improve performer documentation

IR: Improve performer documentation

Disentangle engraver and performer documentation in the Translation
part of the Internals Reference.

Previously performers were treated just like engravers. Their actual
relations to contexts as specified in ly/performer-init.ly was
ignored, since only the layout output description based on
ly/engraver-init.ly ($defaultlayout) was parsed.

For performers, query the $defaultmidi output description now. This
also makes available the music expression types accepted by
performers.

Make sure all contexts get documented. While most contexts appear both
in $defaultlayout and $defautlmidi, there is currently one,
ChordNameVoice, that only appears in $defaultmidi and several that
only appear in $defaultlayout.

Merge engraver and performer information in context descriptions.

Try to consolidate translator terminology in the code. So far,
'engraver' had frequently been used where all types of translators
were meant.

Separate translators, performers and other translators into
subsubsections.

[dak, 2012-12-02 11:11:54]

Improving the docs certainly is quite worthwhile.

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

https://codereview.appspot.com/6868047/diff/1/scm/document-translation.scm#ne...
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?).

[J. Rohrer, 2012-12-02 11:42:09]

On 2012/12/02 11:11:54, dak wrote:
>
https://codereview.appspot.com/6868047/diff/1/scm/document-translation.scm#ne...
> 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?).

I am not sure I quite understand. When are "engravers also used as performers"?
As far as I understand, both are completely separate now (and easily
distinguishable by their names), and my patch actually _does_ separate them into
different subsubsections where they are now all in one flat list. This is
trivially generalizable to new translator types, too.

Your comment would make more sense with regard to contexts. I have refrained
from differentiating between engraver contexts and performer contexts because
the latter mostly duplicate the former, and because you usually don't care about
the distinction while writing LilyPond code.

But I agree that disentagling that further would be programatically cleaner, so
if you prefer that I can prepare a more invasive patch that does so.

[J. Rohrer, 2012-12-31 13:22:44]

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#ne...
> 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