(En passant: I tried \info BarLine but could not see "extra-spacing-width".
See the attached debug)
But in general, I think it's not a good idea to dump these kind of doc
infos as the output of a library, for several reasons.
First of all because it has limitations in formatting and in linking
between different pages. The resulting output is therefore too long to read.
I think it's enough to make some adjustments to the current output of the
autodoc tool.
First one would be to add, with small fonts, at the bottom of the page, a
list of the pairs (as links): class/interface - overriden/implemented
property, inside an expandible panel (hidden by default).
In this way, IF I can't find an useful property in the main panel, THEN I
can look at the implemented interfaces list at the bottom. At this point,
if in this (short) list there's a name that looks interesting, I click on
it without expanding the below panel, and I jump to the linked page. If I
can't guess the right interface, I would expand the below panel and I would
look more accurately in the contained (long) list. This avoids to jump
forth and back from page to page.
In general, I see this as a good default choice for the autodoc of
libraries, but even if it's not set as default, the command to produce a
complete autodoc should be documented as well. In this library (which I
made some years ago and could not update, in the last years)
https://github.com/paolo-pr/laav
you can find a directory for the autodoc (Doxygen) and the instructions to
build it. Then, it is left to the user how much complete or minimal the
autodoc has to be.
Best,
P
On Wed, Nov 10, 2021 at 10:36 PM Jean Abou Samra <[email protected]> wrote:
> [Kieren]
> >> The page in the Internals Reference doesn't
> >> list all the properties that the grob would
> >> support, only those for which it has a specific
> >> default. You have to explore the interfaces to
> >> find other interesting properties that you can
> >> tweak. In this case, click "Item" ("This object
> >> is of class Item"). You'll find extra-spacing-width
> >> in the item-interface.
> > This is something I’ve asked a couple times before, but been dismissed…
> Maybe you can help?
> >
> > Is there an Automagic™ way to print out a “complete tree” of all
> properties that a grob supports, including any default values?
>
>
> Sure. How about the attached?
>
> Bear in mind that this may stop working in future
> versions (in fact I have a branch somewhere that
> would definitely break it if I ever manage to
> complete the work).
>
>
> [Paolo]
> > Thanks.
> >
> > However, when looking for a property or function that might fit what I
> > need, I always check for inherited stuff. In this case, unfortunately,
> > the search is a bit cumbersome and tricky and it's not the first time,
> > especially when the properties are so many and I have to write the
> > code quickly, that I don't find the right property.
> > Suppose that an object has many settable properties: there is a main
> > page of this object, let's call it "A", and other pages with inherited
> > properties (B, C, D, E etc.)
> > When I do a search, I first look inside A: if I don't find anything
> > useful, I look in B and if I don't find anything useful here too, I go
> > back to A and then I go to C etc.
> > You can understand that, when there are so many properties, jumping
> > back and forth from page to page is inconvenient to remember what is
> > available as a sum of things. In many automatic documentation of other
> > libraries I use, the inherited properties and functions are listed
> > grouped (with relative links), sometimes in small format, at the
> > bottom of the page to avoid this inconvenience.
> > It is true that the resulting page is longer, but it is not heavier to
> > read. Furthermore, in this way you can read only the names, without
> > the descriptions, of these properties and this allows you to decide
> > whether or not to jump to the page that defines the inherited property
> > to try. Mine is a suggestion, and I think it's useful to add it to the
> > documentation (or at least explain how to create this "extra"
> > documentation automatically)
>
>
> Would the attached mock a good way to format
> this documentation in your opinion?
>
> Best,
> Jean
>
BarLine
=======
Interfaces supported: grob-interface, bar-line-interface,
break-aligned-interface, font-interface, pure-from-neighbor-interface
Classes: Item
* after-line-breaking (from grob-interface)
-------------------
Dummy property, used to trigger callback for @code{after-line-breaking}.
* allow-span-bar (from bar-line-interface)
--------------
#t
If false, no inter-staff bar line will be created below this bar line.
* avoid-slur (from grob-interface)
----------
Method of handling slur collisions. Choices are @code{inside},
@code{outside}, @code{around}, and @code{ignore}. @code{inside} adjusts
the slur if needed to keep the grob inside the slur. @code{outside}
moves the grob vertically to the outside of the slur. @code{around}
moves the grob vertically to the outside of the slur only if there is a
collision. @code{ignore} does not move either. In grobs whose notational
significance depends on vertical position (such as accidentals, clefs,
etc.), @code{outside} and @code{around} behave like @code{ignore}.
* bar-extent (from bar-line-interface)
----------
ly:bar-line::calc-bar-extent
The Y-extent of the actual bar line. This may differ from
@code{Y-extent} because it does not include the dots in a repeat bar
line.
* before-line-breaking (from grob-interface)
--------------------
Dummy property, used to trigger a callback function.
* break-align-anchor (from break-aligned-interface)
------------------
ly:bar-line::calc-anchor
Grobs aligned to this breakable item will have their X-offsets shifted
by this number. In bar lines, for example, this is used to position
grobs relative to the (visual) center of the bar line.
* break-align-anchor-alignment (from break-aligned-interface)
----------------------------
Read by @code{ly:break-aligned-interface::calc-extent-aligned-anchor}
for aligning an anchor to a grob's extent.
* break-align-symbol (from break-aligned-interface)
------------------
staff-bar
This key is used for aligning, ordering, and spacing breakable items.
See @rinternals{break-alignment-interface}.
* color (from grob-interface)
-----
The color of this grob.
* extra-offset (from grob-interface)
------------
A pair representing an offset. This offset is added just before
outputting the symbol, so the typesetting engine is completely oblivious
to it. The values are measured in @code{staff-space} units of the
staff's @code{StaffSymbol}.
* font-encoding (from font-interface)
-------------
The font encoding is the broadest category for selecting a font.
Currently, only lilypond's system fonts (Emmentaler) are using this
property. Available values are @code{fetaMusic} (Emmentaler),
@code{fetaBraces}, @code{fetaText} (Emmentaler).
* font-family (from font-interface)
-----------
The font family is the broadest category for selecting text fonts.
Options include: @code{sans}, @code{roman}.
* font-features (from font-interface)
-------------
Opentype features.
* font-name (from font-interface)
---------
Specifies a file name (without extension) of the font to load. This
setting overrides selection using @code{font-family}, @code{font-series}
and @code{font-shape}.
* font-series (from font-interface)
-----------
Select the series of a font. Choices include @code{medium}, @code{bold},
@code{bold-narrow}, etc.
* font-shape (from font-interface)
----------
Select the shape of a font. Choices include @code{upright},
@code{italic}, @code{caps}.
* font-size (from font-interface)
---------
The font size, compared to the @q{normal}@tie{}size. @code{0}@tie{}is
style-sheet's normal size, @w{@code{-1}} is smaller, @code{+1} is
bigger. Each step of@tie{}1 is approximately 12% larger; 6@tie{}steps
are exactly a factor@tie{}2 larger. If the context property
@code{fontSize} is set, its value is added to this before the glyph is
printed. Fractional values are allowed.
* footnote-music (from grob-interface)
--------------
Music creating a footnote.
* forced-spacing (from grob-interface)
--------------
Spacing forced between grobs, used in various ligature engravers.
* gap (from bar-line-interface)
---
0.4
Size of a gap in a variable symbol.
* glyph (from bar-line-interface)
-----
"|"
A string determining what @q{style} of glyph is typeset. Valid choices
depend on the function that is reading this property. In combination
with (span) bar lines, it is a string resembling the bar line appearance
in ASCII form.
* glyph-name (from bar-line-interface)
----------
bar-line::calc-glyph-name
The glyph name within the font. In the context of (span) bar lines,
@var{glyph-name} represents a processed form of @code{glyph}, where
decisions about line breaking etc. are already taken.
* hair-thickness (from bar-line-interface)
--------------
1.9
Thickness of the thin line in a bar line, expressed as a multiple of the
default staff-line thickness (i.e. the visual output is @emph{not}
influenced by changes to @code{@var{Staff}.StaffSymbol.thickness}).
* horizontal-skylines (from grob-interface)
-------------------
Two skylines, one to the left and one to the right of this grob.
* id (from grob-interface)
--
An id string for the grob.
* kern (from bar-line-interface)
----
3.0
The space between individual elements in any compound bar line,
expressed as a multiple of the default staff-line thickness (i.e. the
visual output is @emph{not} influenced by changes to
@code{@var{Staff}.StaffSymbol.thickness}).
* layer (from grob-interface)
-----
0
An integer which determines the order of printing objects. Objects with
the lowest value of layer are drawn first, then objects with
progressively higher values are drawn, so objects with higher values
overwrite objects with lower values. By default most objects are
assigned a layer value of 1.
* minimum-X-extent (from grob-interface)
----------------
Minimum size of an object in X@tie{}dimension, measured in
@code{staff-space} units.
* minimum-Y-extent (from grob-interface)
----------------
Minimum size of an object in Y@tie{}dimension, measured in
@code{staff-space} units.
* output-attributes (from grob-interface)
-----------------
An alist of attributes for the grob, to be included in output files.
When the SVG typesetting backend is used, the attributes are assigned to
a group (@code{<g>}) containing all of the stencils that comprise a
given grob. For example, @example '((id . 123) (class . foo)
(data-whatever . "bar")) @end example @noindent produces @example <g
id="123" class="foo" data-whatever="bar"> @dots{} </g> @end example In
the Postscript backend, where there is no way to group items, the
setting of the @code{output-@/attributes} property has no effect.
* parenthesis-friends (from grob-interface)
-------------------
A list of Grob types, as symbols. When parentheses enclose a Grob that
has 'parenthesis-friends, the parentheses widen to include any child
Grobs with type among 'parenthesis-friends.
* parenthesis-id (from grob-interface)
--------------
When parenthesized grobs created in the same time step have this
property, there is one set of parentheses for each group of grobs having
the same value.
* parenthesized (from grob-interface)
-------------
Parenthesize this grob.
* rotation (from grob-interface)
--------
Number of degrees to rotate this object, and what point to rotate
around. For example, @code{'(45 0 0)} rotates by 45 degrees around the
center of this object.
* rounded (from bar-line-interface)
-------
#f
Decide whether lines should be drawn rounded or not.
* segno-kern (from bar-line-interface)
----------
3.0
The space between the two thin lines of the segno bar line symbol,
expressed as a multiple of the default staff-line thickness (i.e. the
visual output is @emph{not} influenced by changes to
@code{@var{Staff}.StaffSymbol.thickness}).
* skyline-horizontal-padding (from grob-interface)
--------------------------
For determining the vertical distance between two staves, it is possible
to have a configuration which would result in a tight interleaving of
grobs from the top staff and the bottom staff. The larger this parameter
is, the farther apart the staves are placed in such a configuration.
* space-alist (from break-aligned-interface)
-----------
((ambitus extra-space . 1.0)
(time-signature extra-space . 0.75)
(custos minimum-space . 2.0)
(clef extra-space . 1.0)
(key-signature extra-space . 1.0)
(key-cancellation extra-space . 1.0)
(first-note fixed-space . 1.3)
(next-note semi-fixed-space . 0.9)
(right-edge extra-space . 0.0))
An alist that specifies distances from this grob to other breakable
items, using the format: @example '((@var{break-align-symbol} .
(@var{spacing-style} . @var{space})) (@var{break-align-symbol} .
(@var{spacing-style} . @var{space})) ...) @end example Standard choices
for @w{@code{@var{break-align-symbol}}} are listed in
@rinternals{break-alignment-interface}. Additionally, three special
@w{break-align} symbols available to @w{@code{space-alist}} are:
@quotation @table @code @item first-note used when the grob is just left
of the first note on a line @item next-note used when the grob is just
left of any other note; if not set, the value of @code{first-note} gets
used @item right-edge used when the grob is the last item on the line
(only compatible with the @w{@code{extra-space}} spacing style) @end
table @end quotation Choices for @code{@var{spacing-style}} are:
@quotation @table @code @item extra-space Put this much space between
the two grobs. The space is stretchable when paired with
@w{@code{first-note}} or @w{@code{next-note}}; otherwise it is fixed.
@item minimum-space Put at least this much space between the left sides
of both grobs, without allowing them to collide. The space is
stretchable when paired with @w{@code{first-note}} or
@w{@code{next-note}}; otherwise it is fixed. Not compatible with
@w{@code{right-edge}}. @item fixed-space Only compatible with
@w{@code{first-note}} and @w{@code{next-note}}. Put this much fixed
space between the grob and the note. @item minimum-fixed-space Only
compatible with @w{@code{first-note}} and @w{@code{next-note}}. Put at
least this much fixed space between the left side of the grob and the
left side of the note, without allowing them to collide. @item
semi-fixed-space Only compatible with @w{@code{first-note}} and
@w{@code{next-note}}. Put this much space between the grob and the note,
such that half of the space is fixed and half is stretchable. @end table
@end quotation Rules for this spacing are much more complicated than
this. See [Wanske] page 126--134, [Ross] page 143--147.
* springs-and-rods (from grob-interface)
----------------
Dummy variable for triggering spacing routines.
* stencil (from grob-interface)
-------
ly:bar-line::print
The symbol to print.
* thick-thickness (from bar-line-interface)
---------------
6.0
Thickness of the thick line in a bar line, expressed as a multiple of
the default staff-line thickness (i.e. the visual output is @emph{not}
influenced by changes to @code{@var{Staff}.StaffSymbol.thickness}).
* transparent (from grob-interface)
-----------
This makes the grob invisible.
* vertical-skylines (from grob-interface)
-----------------
Two skylines, one above and one below this grob.
* whiteout (from grob-interface)
--------
If a number or true, the grob is printed over a white background to
white-out underlying material, if the grob is visible. A number
indicates how far the white background extends beyond the bounding box
of the grob as a multiple of the staff-line thickness. The
@code{LyricHyphen} grob uses a special implementation of whiteout: A
positive number indicates how far the white background extends beyond
the bounding box in multiples of @code{line-thickness}. The shape of the
background is determined by @code{whiteout-style}. Usually @code{#f} by
default.
* whiteout-style (from grob-interface)
--------------
Determines the shape of the @code{whiteout} background. Available are
@code{'outline}, @code{'rounded-box}, and the default @code{'box}. There
is one exception: Use @code{'special} for @code{LyricHyphen}.
* X-extent (from grob-interface)
--------
Extent (size) in the X@tie{}direction, measured in staff-space units,
relative to object's reference point.
* X-offset (from grob-interface)
--------
The horizontal amount that this object is moved relative to its
X-parent.
* Y-extent (from grob-interface)
--------
#<unpure-pure-container #<primitive-procedure ly:grob::stencil-height> >
Extent (size) in the Y@tie{}direction, measured in staff-space units,
relative to object's reference point.
* Y-offset (from grob-interface)
--------
The vertical amount that this object is moved relative to its Y-parent.
