Re: RFC: Embedded documentation

Hi Nicolas

On Mon, Apr 27, 2026 at 07:29:51PM +0200, 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?

yes


> 
> 
> 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.

I consider the general decision to have embedded documentation separate
from the review of the particular APIs needed to implement it.


> 
> 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.

This is an ambitious project; it is not simple.

For example, localization becomes more important once applications use
documentation obtained directly from the libraries.

Also, where and how should the data be stored? Our texi documentation is
currently around 2-3 MB, or roughly 500 kB compressed, although one could
argue that compression does not belong at this layer.

I think some important goals are:

* It should be easy to maintain. Once implemented, it should not add a
  significant maintenance burden compared to today.

* Documentation should not be duplicated, since duplicated documentation
  will inevitably drift.

Code and API details will of course be subject to the usual review.

However, objections to the project in principle need to be raised now.
It would not be reasonable for Nicolas to spend substantial time
implementing this and then have the result rejected because embedded
documentation is considered not to belong in FFmpeg.

that said, iam in favor of this, if nicolas wants to work on this!

thx

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

When you are offended at any man's fault, turn to yourself and study your
own failings. Then you will forget your anger. -- Epictetus

_______________________________________________
ffmpeg-devel mailing list -- [email protected]
To unsubscribe send an email to [email protected]

-----BEGIN PGP SIGNATURE-----

iF0EABEKAB0WIQSf8hKLFH72cwut8TNhHseHBAsPqwUCan+G+gAKCRBhHseHBAsP
q/EMAJ9pveFxKCLVv9trRlTMW/3t6pAsEwCdHCYQB+9Ch8631iOR/V4YL4TqHVM=
=+9X8
-----END PGP SIGNATURE-----