On 2026-04-27 10:59 pm, Nicolas George via ffmpeg-devel wrote:
Hi.
If I manage to make more time and to motivate myself to spend them on
FFmpeg (the issues with forgejo do not help…), one of the projects I
would like to work on is embedded documentation.
The idea is to have a copy of the documentation within the read-only
parts of the libraries in a structured format, so that interactive
applications can access it and show to the users exactly what they need.
To make things clear, this is the kind of code I would like to make
possible (omitting error checks):
char *doc = av_doc_get_as_string(button->ctx, AV_DOC_SHORT |
AV_DOC_PLAINTEXT);
gtk_widget_set_tooltip(button->widget, doc);
(in case it is not self-explanatory: ask lav* for a short string in
plain text that document a context associated to a GUI button and set it
as the tooltip for the button)
or:
create_temp_file(&tmpfile);
av_doc_get_to_file(ctx, tmpfile, AV_DOC_LONG | AV_DOC_HTML_DOC);
spawn_web_browser(url_for(tmpfile));
(in case it is not self-explanatory: prepare a temporary file, ask lav*
to write into it a long documentation in HTML for a component and open a
web browser to display it)
Of course, the same API would allow to expand the -h option of our own
command-line tools.
The short documentation would contain only the short description of the
component and its options, maybe only the most important ones. The long
description would include the explanation paragraphs, the examples, the
documentation for the syntax of the options, the explanations for the
concepts they involve, everything necessary. Intermediate levels of
detail are possible.
The first question I want to ask is: Do we want it?
If the collective answer is no, then I can stop thinking about it and
move to something else.
If the collective answer is yes, then we can discuss in more details.
But it also means we want everything that is necessary to implement it.
And since it produces text, that includes AVWriter. Also, it probably
includes reworking the way the documentation is stored in files in the
source code, maybe changing its format.
Note: I am not interested in a less ambitious system. A version where we
just add a few text fields to components and let applications deal with
them, without transverse documentation like the syntax for timestamps,
is absolutely possible, but I would not be the one to work on it.
I hope the answer is yes.
Yes, in theory. The devil, of course, is in the actual implementation.
Ideally, the internal API you propose should not be the only mediator;
the data should be structured text that even an external tool can parse.
Regards,
Gyan
_______________________________________________
ffmpeg-devel mailing list -- [email protected]
To unsubscribe send an email to [email protected]
