Le 10/11/2021 à 22:49, Carl Sorensen a écrit :
The code looks way cool. Unfortunately, I couldn't test it because I only have
2.22 installed, and it doesn't work with 2.22 (perhaps because of guile 1.8)
I tested it with the official 2.23.4 binaries,
which still use Guile 1.8. The failure is due
to a change (by me) that allowed the same grob
definition to be used to make both items and
spanners, mostly to support all kinds of annotations
better, unifying FootnoteItem and FootnoteSpanner
for example.
A new version with fixes is attached. To give you
an idea, here's an excerpt from its output:
Footnote
########
Interfaces supported: balloon-interface, font-interface, footnote-interface,
grob-interface, item-interface [when created with class Item],
spanner-interface [when created with class Spanner], sticky-grob-interface,
text-interface
Classes: Item, Spanner
Properties with default value:
==============================
* annotation-balloon (from balloon-interface)
------------------
#f
Print the balloon around an annotation.
[...]
* stencil (from grob-interface)
-------
ly:balloon-interface::print
The symbol to print.
* text (from balloon-interface, text-interface)
----
#f
Text markup. See @ruser{Formatting text}.
[...]
Other properties supported:
===========================
* after-line-breaking (from grob-interface)
-------------------
Dummy property, used to trigger callback for @code{after-line-breaking}.
[...]
* extra-spacing-height (from item-interface [when created with class Item])
--------------------
In the horizontal spacing problem, we increase the height of each item
by this amount (by adding the @q{car} to the bottom of the item and
adding the @q{cdr} to the top of the item). In order to make a grob
infinitely high (to prevent the horizontal spacing problem from placing
any other grobs above or below this grob), set this to @code{(-inf.0 .
+inf.0)}.
(En passant: I tried \info BarLine but could not see
"extra-spacing-width". See the attached debug)
Correct, this is fixed in the file attached.
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.
Sure, hence "mock": it wasn't meant to become an official
solution, just to address Kieren's request and at the same
time provide some food for thought and experimentation.
Once the code to organize the information is in place, it's
easy to make it produce Texinfo input and integrate it to
the main autogeneration infrastructure.
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.
Why not, but I'm not 100% conviced by the the principle of
a collapsible section, partly because this still requires
a number of clicks, and and partly because we have to
do with the tool we have (Texinfo) and the formats we
generate (not only HTML but also PDF and Info). However,
I admit that the page was overwhelming in the first version.
In the second one attached, I'm grouping the properties with
defaults in a first section so one does not have to scroll
to see the main definition. The others are separated
in a second section.
At any rate, this is getting specific enough that we would
better move the discussion to a channel dedicated to
development. I've just opened a tracker issue for this:
https://gitlab.com/lilypond/lilypond/-/issues/6210
Best,
Jean