Hi Michael,
Am 31.03.26 um 08:44 schrieb Michael Scheer:
Important question. I didn't yet understand how and where I approach
the docs and maybe source code? when questions like these arise:
a) I have \staffHighlight - where can I look it up? Where do I find
description of it's properties? methods? like "shorten-pair"? Can I
maybe have a deeper look into the Scheme foundation of \staffHighlight?
b) This is somewhat part of "Horizontal_bracket_engraver" - where will
I find description, properties/methods doc, its code?
The doc situation is not ideal at the moment if you happen to have your
browser set to (e.g.) German as default language: Then the LilyPond web
page always shows the translated version of the documentation first,
which for some languages is _seriously_ lagging behind the current state
of LilyPond. (Translators are always welcome!)
The English documentation is always up to date.
For users willing to dive into the Scheme codebase, the parts of
LilyPond that are written in Scheme can be viewed (and re-used) in any
installed version of LilyPond. For \staffHighlight and friends, search
for a file called property-init.ly on your computer. But, frankly, this
sort of inspection is much more fun with a LilyPond source tree, so if
you're used to dealing with that sort of thing, you can clone the git
repository (https://gitlab.com/lilypond/lilypond) and get the comfort of
'git grep' etc.
Namely, in property-init.ly, you see that the \staffHighlight function
itself only creates a StaffHighlightEvent, so there must be a dedicated
engraver handling this event. This engraver may be found in the file
scheme-engravers.scm (search for Staff_highlight_engraver in this file).
There we see that this engraver then creates StaffHighlight grobs (the
actual colored things), the properties of which are in turn defined in
the file define-grobs.scm. There we find:
(StaffHighlight
. (
(bound-prefatory-paddings . (0.5 . 0.5))
(color . ,(grob::calc-property-by-copy 'color))
(layer . -1)
(shorten-pair . (0 . 0))
(stencil . ,staff-highlight::print)
(X-extent . ,staff-highlight::width)
(Y-extent . ,staff-highlight::height)
(meta . ((class . Spanner)
(interfaces . (staff-highlight-interface))
(description . "A colored span to highlight a music
passage.")))))
In particular, the actual printed ink is created in the stencil callback
staff-highlight::print, which in turn is defined in output-lib.scm,
where we find.
Part of this information (which I obtained by grep'ping the source tree)
is contained in the Internals manual:
https://lilypond.org/doc/v2.24/Documentation/internals/staffhighlight.
You'll notice that this is simply the information from define-grobs.scm
(but the machinery generating the documentation doesn't seem equipped to
handle the grob::calc-property-by-copy callback, ugh).
So this is a little bit of a chase through the source tree. (Others
might have more efficient routines of working.)
For understanding the mechanism, it is sometimes easier to just look at
the commit that added the functionality (but of course the current state
of things might have evolved considerably by now). "git log" helps find
out that the relevant commit is:
commit 57d313da56072a21fded8c97c990d66b4e8bd240
Author: Jean Abou Samra <[email protected]>
Date: Fri Aug 12 11:32:50 2022 +0200
Add staff highlights
Viewing this commit (with gitk for example) shows how the changes Jean
introduced for this feature are ditributed across the source tree.
One word of caution: The LilyPond source code is distributed between C++
and Scheme code. Over the past years, a quite large number of engravers
etc. have been moved from C++ to Scheme (or, as in the case of
StaffHighlight, have been written in Scheme in the first place). But for
the more essential parts of LilyPond, one quickly finds oneself in the
C++ part of the source.
Sorry if this was more information (or different information) than you'd
hoped for. :-)
Lukas
