Re: IR: Improve performer documentation (issue 6868047)

[src]

Reviewers: dak,

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

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?).

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.

Description:
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.

Please review this at https://codereview.appspot.com/6868047/

Affected files:
  M scm/document-music.scm
  M scm/document-translation.scm