[FFmpeg-devel] Embedded documentation?

[Nicolas George]

Stefano Sabatini (12023-05-08):
> I cannot parse this, where is the threshold value defined?

The threshold is the enum constant that was being described.

> Maybe an example would clarify this, since there is ambiguity about
> what default and explanations are.

Let us think how this is meant to be used. For example, the user of a
GUI clicks on a filter, the application asks the library “give me the
documentation for this” and displays it somewhere.

Imagine the whole FFmpeg documentation as a gigantic hypertext document,
like <https://ffmpeg.org/ffmpeg-all.html>. Imagine we want the
documentation for the scale filter. So we start at
<https://ffmpeg.org/ffmpeg-all.html#scale-1>, and we take:

- the introduction of the scale filter,
- the width option,
- the height option,
- the flags option,
- the size option,
- etc.,
- the examples,
- the commands,

But the width and height options are expressions, therefore we will need
also <https://ffmpeg.org/ffmpeg-all.html#Expression-Evaluation>.
And the size option is a video size, so we take
<https://ffmpeg.org/ffmpeg-all.html#Video-size> too.
And the flags option requires
<https://ffmpeg.org/ffmpeg-all.html#Scaler-Options>.
And maybe the various scaler flags link to explanations about their pros
and cons, and we want these explanations too.

In general, to get the documentation for a component, avdoc starts at
the doc node of this component, and it follows all the links from there,
and then all the links from the nodes reached, etc., recursively, until
avdoc has all the documentation that might be useful to understand that
component. Then it returns to the application.

But that means we will get 50 pages of documentation for most
components. It is fine to display in a full-fledged help browser, but a
50 pages tooltip is not very convenient.

This is where the thresholds come into play:

- if you want a tooltip, av_documentation_get_excerpt(obj, 0);

- if you want a help dialog where scrolling is possible,
  av_documentation_get_excerpt(obj, AVDOC_LINK_SELF_CONTAINED);

- if you want a help browser where hyperlinks are possible,
  av_documentation_get_excerpt(obj, AVDOC_LINK_SELF_CONTAINED_FULL).

Regards,

-- 
  Nicolas George
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20230508/ecfa6521/attachment.sig>