Re: What is the `bracket-text` property good for?

[Thomas Morley]

Am Mi., 11. Dez. 2024 um 12:49 Uhr schrieb Werner LEMBERG <wl@gnu.org>:
>
>
> >> What are these properties good for?  What can they do what the
> >> `text` property of `HorizontalBracket` or `PianoPedalBracket`
> >> cannot?
> >
> > 'text is a grob-property to set the text for HorizontalBracketText.
> > 'bracket-text (as an internal property) is a pointer from
> > HorizontalBracket to its HorizontalBracketText-grob.
>
> OK, thanks.  The description misses this information; I will update it
> accordingly.

Actually, the descriprion is wrong, imho.
(bracket-text ,ly:grob? "The text for an analysis bracket.")
should become something at he lines of:
(bracket-text ,ly:grob? "The text-grob for an analysis bracket.")

>
> > Completely different. And I would not want to miss 'bracket-text.
>
> Can you please give an example how to use it (or a link to something
> similar)?

I took horizontal-bracket-texted.ly from our regtests and added
functionality in \layout to emphasize some brackets with thickness and
color relying on the 'text.
This would have not been possible without the 'bracket-text pointer,
at least not as an override of HorizontalBracket:

emphasizeCertainBrackets =
  \override HorizontalBracket.after-line-breaking =
    #(lambda (grob)
      (let* ((bracket-text-grob (ly:grob-object grob 'bracket-text))
             (text (ly:grob-property bracket-text-grob 'text)))
          (cond ((equal? text "a")
                  (ly:grob-set-property! grob 'thickness 6)
                  (ly:grob-set-property! bracket-text-grob 'color '(0 1 0))
                  (ly:grob-set-property! grob 'color '(0 1 0)))
                ((equal? text "b")
                  (ly:grob-set-property! grob 'thickness 6)
                  (ly:grob-set-property! bracket-text-grob 'color '(0 0.8 0))
                  (ly:grob-set-property! grob 'color '(0 0.8 0)))
                (else '()))))

\layout {
  \context {
    \Voice
    \consists "Horizontal_bracket_engraver"
    \override HorizontalBracket.direction = #UP
    \emphasizeCertainBrackets
  }
}

\relative c'' {
  \time 3/4
  \key f \major
  c4\tweak HorizontalBracketText.text "contrasting period"
    \tweak outside-staff-priority #801
      \startGroup
    \tweak HorizontalBracketText.text "a"
      \startGroup
  a8( bes c f)
  f4( e d)
  c d8( c bes c)
  \appoggiatura bes4 a2 g4\stopGroup
  \once\override HorizontalBracketText.text = "b"
  f'8 \startGroup
  r a, r d r
  c4( e, f)
  g8( bes) a4 g8( f)
  f2 \stopGroup \stopGroup r4
}

> As mentioned earlier, neither `bracket-text` nor
> `pedal-text` are used anywhere in the code.

Well, yes. Though if you go through those internal properties then you
will notice that a plethora of them are not used in the .scm-files.
Some examples:
accidental-grobs
all-elements
concurrent-hairpins
...

If all of those seemingly unused pointers were deleted than LilyPond
stops its life as programmable software.

For pedal-text the description is misleading, though - I'd go for
text-grob as well.
For an usage-example see the code-attachment of:
https://lists.gnu.org/archive/html/lilypond-user/2018-04/msg00427.html

I may find other usage-examples to most of those seemingly unused
properties, but to be honest, I'd prefer to spend my time at other
tasks :)

Cheers,
  Harm