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
), 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
.]


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/

___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel

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



___
lilypond-devel mailing list
lilypond-devel@gnu.org
https://lists.gnu.org/mailman/listinfo/lilypond-devel