Re: Some things need need to be fixed on the interfaces pages

[Christopher Heckman]

On Tue, Dec 10, 2024 at 9:38 PM Werner LEMBERG <wl@gnu.org> wrote:
>
> >> The policy of LilyPond is to avoid different property names for
> >> similar functionality, which often leads to cryptic property
> >> descriptions to be as generic as possible.  In this particular case
> >> an example is given, which is actually a good thing, but it doesn't
> >> cover the `centered-spanner-interface` incarnation of this
> >> property.
> >>
> >> Maybe you can suggest a better wording for the description of
> >> `spacing-pair`?
> >> [...]
> >
> > On the centered-spanner-interface page, the comment about the
> > MultiMeasureRest can just be deleted (as it's already on the
> > multi-measure-interface page, as long as the description of
> > spacing-pair is correct.
>
> Exactly this is not possible, because there exists only a single,
> global property called `spacing-pair`, which consequently has a
> single, global description.
>
> In other words, the auto-generated documentation sees that an
> interface uses `spacing-pair`, and it shows its description.
>
> IIRC, a suggestion in the mentioned thread

Do you know the name of that thread? I tried searching for it, but
couldn't come up with anything.

--- Chris

> is to make the property
> description displayed for a given grob show which interfaces it is
> part of, for example
>
> ```
> ‘spacing-pair’ (pair)
>      interface(s):
>           centered-spanner-interface, multi-measure-interface
>      default value:
>           '(break-alignment . break-alignment)
>
>      A pair of alignment symbols which set an object's spacing
>      relative to its left and right ‘BreakAlignment’s.
>
>      For example, a ‘MultiMeasureRest’ will ignore prefatory items
>      at its bounds (i.e., clefs, key signatures and time
>      signatures) using the following override:
>
>           \override MultiMeasureRest.spacing-pair =
>                        #'(staff-bar . staff-bar)
> ```
>
> On the description page for `centered-spanner-interface` it could
> display the following:
>
> ```
> ‘spacing-pair’ (pair)
>      also used in:
>           multi-measure-interface
>
>      A pair of alignment symbols which set an object's spacing
>      relative to its left and right ‘BreakAlignment’s.
>
>      For example, a ‘MultiMeasureRest’ will ignore prefatory items
>      at its bounds (i.e., clefs, key signatures and time
>      signatures) using the following override:
>
>           \override MultiMeasureRest.spacing-pair =
>                        #'(staff-bar . staff-bar)
> ```
>
> >> What instrument(s) do you have in mind?  It is possible to improve
> >> the description while talking about 'left hand' and 'right hand' in
> >> the context of fretted instruments, but I don't think it makes
> >> sense to change these long-established terms.
> >
> > The main instrument I'm thinking of is the guitar.
>
> OK, I see.  The probably simplest solution is to explicitly mention
> that LilyPond uses the term 'right hand' to actually indicate the
> strumming hand.
>
> > And there's actually precedent, in that left-handed chord diagrams
> > (FretBoards) are supported by Lilypond.
>
> Well, this makes sense, because they are displayed differently.
>
>
>     Werner

--- Christopher Carl Heckman