Re: [FFmpeg-devel] Embedded documentation?

[Nicolas George]

Stefano Sabatini (12023-05-08):
> Can you share more details about the plan? In particular, is the doc
> going to be embedded in the code itself (e.g. in the C
> implementation)? Or should we have some dedicated headers containing
> the docs?
> 
> We should also avoid to duplicate the same information between docs
> and code, so there should be some way to autogenerate the docs from
> the corresponding entries in the code.

This is far from settled, but I imagine something like that:

- Short doc paragraphs go directly in the C source code as comments with
  a specific markup, like doxygen but distinct from it.

- Longer doc texts go in a file with the same name as the C source code
  but a different extension, probably .md.

- The build system parses all this to generate source files with the
  structured documentation to be compiled into the library.

- The build system can also parse parts of the C source code to extract
  the structure information, for example AVOption initializers.

- The build system also parses the current texinfo documentation so that
  we do not have to rewrite it all at once.

Regards,

-- 
  Nicolas George


signature.asc
Description: PGP signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Nicolas George]

Zhanbang He (12023-05-08):
> Can it supports chatGPT?

Of course not. Only ChatGnuTP, for obvious reasons of freedom.

Regards,

-- 
  Nicolas George


signature.asc
Description: PGP signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Zhanbang He]

Can it supports chatGPT?

On Monday, May 8, 2023, Nicolas George  wrote:

> 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 . Imagine we want the
> documentation for the scale filter. So we start at
> , 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 .
> And the size option is a video size, so we take
>  too.
> And the flags option requires
> .
> 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
>
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [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 . Imagine we want the
documentation for the scale filter. So we start at
, 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 .
And the size option is a video size, so we take
 too.
And the flags option requires
.
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


signature.asc
Description: PGP signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Nicolas George]

Stefano Sabatini (12023-05-08):
> I think the problem with HTML is that then you need to parse it if you
> want to display it, so I'd tend to rather go with markdown:
> 1. it provides readable raw output
> 2. there are plenty of libraries which can render it to various
> formats (including HTML)

I will reply to this separately.

A lot of your comments are a little premature: I am not ready to start
working on this just now. For starters, it is out of question without
AVWriter being committed, and I am still waiting for somebody who is not
a-priori hostile and who understand strings to look at the code.

But this issue can be discussed now.

I think using Markdown internally would be a huge mistake.

You say “it provides readable raw format”: you seem to be assuming
ffmpeg/ffplay/ffprobe will dump the documentation to the terminal as is
and be done with it, and all other kinds of applications will have to
manage the rest themselves.

Well, this is not the kind of API I want to design. I want an API where
we provide to the applications all its needs to prepare the
documentation for the user, with the data in the most convenient format.

And for that, the internal format needs to be convenient to manage with
a program. A C program specifically.

Markdown is designed to be easy to type and easy to look at by humans.
But that makes it terrible to manage with a program. For starters, its
syntax is highly ambiguous, already with “*” and “**”.

HTML is a much better choice. Note: I am not suggesting the full complex
beast of HTML found on the world-wide-web, with CSS and javascript and
bad syntax and all the crap. I am suggesting a very well-defined subset
of clean HTML. That is much easier to parse than Markdown, with only <
and & acting as special characters.

Regards,

-- 
  Nicolas George


signature.asc
Description: PGP signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Stefano Sabatini]

On date Monday 2023-05-01 12:13:09 +0200, Nicolas George wrote:
> Hi.
> 
> Three years ago, I shared some brief thoughts about embedding the
> documentation in the libraries. For example, that would allow GUI
> applications to open help dialogs about specific options.
> 
> To see what it would need, I wrote the following header. I did not work
> any further, because groundwork need to be laid first. But now that it
> was mentioned in another thread, I think it is a good idea to show it,
> to see how people like it.
> 
> Please share your remarks. Even “+1” to say you like it, because people
> who will not like it will not hesitate to post “-1”.
> 
> Regards,
> 
> -- 
>   Nicolas George

> typedef struct AVDocNode AVDocNode;
> typedef struct AVDocLink AVDocLink;
> typedef enum AVDocNodeType AVDocNodeType;
> typedef enum AVDocLinkType AVDocLinkType;
> 
> /**
>  * Link to another documentation node.
>  */
> struct AVDocLink {
> AVDocNode *target;
> AVDocLinkType type;
> };
> 
> /**
>  * Node in the documentation system.
>  *
>  * A node can be the description of a codec, format, filter, option, type,
>  * etc.
>  */
> struct AVDocNode {
> 
> /**
>  * Names of the component.
>  *
>  * It is a concatenation of 0-terminated strings, terminated by an empty
>  * string (i.e. a double 0).

>  * For example "frame_rate, rate, r" would be "frame_rate\0rate\0r\0\0".
>  * The first name is the main name of the component, the other are
>  * aliases.

I'd prefer to use something easily parsable and still more
human-readable, such as "frame_rate,rate,r"

>  * If this field is used as a plain C string, it contains only the main
>  * name.
>  */
> const char *names;
> 
> /**
>  * Unique identifier of the compnent.
>  *
>  * It is composed of alphanumeric characters plus underscore and slash
>  * and written hierarchically.
>  *

>  * For example, the width option of the scale filter would be
>  * "lavfi/vf_scale/opt_width".

maybe something as:
lavfi/scale/option:width

the name of a filter is unique, and we don't want to expose the
internals of the library (vf_, af_ etc. - also they don't make much
sense for multi/trans-media filters)

>  *
>  * This identifier can be used for links in the text.
>  *
>  * It matches the symbol that makes the documentation available, in the
>  * avdoc_ namespace with double underscore standing for slashes:
>  * extern const AVDocNode avdoc_lavfi__vf_scale__opt_width;
>  */
> const char *id;
> 
> /**
>  * Title / short description, possibly NULL.
>  *
>  * Can be used in a table of contents for example.
>  */
> const char *title;
> 

> /**
>  * Text of the documentation in XXX Markdown / FFHTML.
>  *
>  * Apparently we want to write the documentation in Markdown or similar,
>  * but the build system can convert when creating the data structure to
>  * embed in the library.
>  *
>  * On one hand, Markdown can be dumped as is to the user, in a terminal
>  * or a basic dialog box.
>  *
>  * On the other hand, strict minimalist HTML is more program-friendly,
>  * which makes it more convenient for programs that want to display it
>  * with actual italics 
>  *
>  * I think FFHTML (i.e. a small, strict and clearly documented subset of
>  * HTML) would be better.
>  */
> const char *text;

I think the problem with HTML is that then you need to parse it if you
want to display it, so I'd tend to rather go with markdown:
1. it provides readable raw output
2. there are plenty of libraries which can render it to various
formats (including HTML)

> 
> /**
>  * Object about which the documentation is.
>  *
>  * If not NULL, points to an object starting with an AVClass pointer.
>  */
> void *object;
> 
> /**
>  * Links towards other nodes.
>  *
>  * All nodes linked in the text must have an entry here, but implicit
>  * links are possible too, for example the type of an option.
>  *
>  * The types are ordered by type.
>  */
> const AVDocLink *links;
> 

> /**
>  * Type of the node, and of the object documented.
>  */
> AVDocNodeType type;

We already define AV_CLASS_CATEGORY (libavutil/log.h), could it be
adjusted for this scope?

> };
> 
> /**
>  * Type of a documentation node.
>  */
> enum AVDocNodeType {
> AVDOC_TYPE_GENERIC = 0,
> AVDOC_TYPE_MUXER,
> AVDOC_TYPE_DEMUXER,
> AVDOC_TYPE_ENCODER,
> AVDOC_TYPE_DECODER,
> AVDOC_TYPE_FILTER,
> AVDOC_TYPE_BITSTREAM_FILTER,
> AVDOC_TYPE_SWSCALER,
> AVDOC_TYPE_SWRESAMPLER,
> AVDOC_TYPE_DEVICE_VIDEO_OUTPUT,
> AVDOC_TYPE_DEVICE_VIDEO_INPUT,
> AVDOC_TYPE_DEVICE_AUDIO_OUTPUT,
> AVDOC_TYPE_DEVICE_AUDIO_INPUT,
> AVDOC_TYPE_DEVICE_OUTPUT,
> AVDOC_TYPE_DEVICE_INPUT,
> AVDOC_TYPE_OPTION,
> AVDOC_TYPE_TYPE,
> 

Re: [FFmpeg-devel] Embedded documentation?

[Thilo Borgmann]

Hi,


Three years ago, I shared some brief thoughts about embedding the
documentation in the libraries. For example, that would allow GUI
applications to open help dialogs about specific options.

To see what it would need, I wrote the following header. I did not work
any further, because groundwork need to be laid first. But now that it
was mentioned in another thread, I think it is a good idea to show it,
to see how people like it.

Please share your remarks. Even “+1” to say you like it, because people
who will not like it will not hesitate to post “-1”.


+1.

I certainly like the idea. Not thinking ahead about any details except that for 
custom very small builds, one should be able to disable this feature.

-Thilo
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Nicolas George]

Timo Rothenpieler (12023-05-01):
> Somewhat loosely related to this:
> 
> A frequent issue is that it's entirely non-obvious which global libavcodec
> options a codec might make use of.
> Having a way to self-document that would be amazing, so those options show
> up in the --help output, ideally with their codec-specific default.

Interesting remark. I also thought in the past that knowing if a certain
component uses or ignore a particular common option would be useful, but
I had not pushed the reflexion to that point.

> The obvious idea I had for this was to utilize the FFCodecDefault struct
> which already exists, maybe expanding it a tiny bit to allow the second
> value to be NULL, indicating "This codec uses that option, but does not
> change the default".
> 
> Main issue with this is that FFCodecDefault is a private struct.
> It could just be made public and user-queryable, while making every current
> user of it aware of possible NULL-values, which they can then just ignore.

I can imagine a few other solutions.

Note that the way we store the information in the library does not have
to be the same as the way we give that information to the user. For
example, internally we could store an array of used or unused options
and to the user we can include only the used options in AVDocExcerpt.

The most annoying task for this will be to look at the code component by
component.

Regards,

-- 
  Nicolas George


signature.asc
Description: PGP signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Nicolas George]

Diederick C. Niehorster (12023-05-01):
> +1.

Thanks.

> I assume a lot of the AVDocNode can be automatically populated from its
> corresponding option? We'd not want to maintain, e.g. option names and
> aliases in more than one place.

I cannot promise there will be no duplication at all, and AVOption is
very limited and needs to be replaced anyway.

But I can promise it will not have to be written as a C structure with
all its fields initialized.

I have not discussed it nor finalized any of the details, but I am
thinking the build system will parse either doxy-style comments in the C
source code or in a separate .md file with the same name to generate the
structures for the built-in documentation. If the system parses comments
in the C source, it can also parse the AVOption initializers, at least
in the simple cases.

Regards,

-- 
  Nicolas George


signature.asc
Description: PGP signature
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Timo Rothenpieler]

On 01.05.2023 12:13, Nicolas George wrote:

Hi.

Three years ago, I shared some brief thoughts about embedding the
documentation in the libraries. For example, that would allow GUI
applications to open help dialogs about specific options.

To see what it would need, I wrote the following header. I did not work
any further, because groundwork need to be laid first. But now that it
was mentioned in another thread, I think it is a good idea to show it,
to see how people like it.

Please share your remarks. Even “+1” to say you like it, because people
who will not like it will not hesitate to post “-1”.

Regards,


Somewhat loosely related to this:

A frequent issue is that it's entirely non-obvious which global 
libavcodec options a codec might make use of.
Having a way to self-document that would be amazing, so those options 
show up in the --help output, ideally with their codec-specific default.


The obvious idea I had for this was to utilize the FFCodecDefault struct 
which already exists, maybe expanding it a tiny bit to allow the second 
value to be NULL, indicating "This codec uses that option, but does not 
change the default".


Main issue with this is that FFCodecDefault is a private struct.
It could just be made public and user-queryable, while making every 
current user of it aware of possible NULL-values, which they can then 
just ignore.

___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

Re: [FFmpeg-devel] Embedded documentation?

[Diederick C. Niehorster]

On Mon, May 1, 2023 at 12:13 PM Nicolas George  wrote:

> Hi.
>
> Three years ago, I shared some brief thoughts about embedding the
> documentation in the libraries. For example, that would allow GUI
> applications to open help dialogs about specific options.
>
> To see what it would need, I wrote the following header. I did not work
> any further, because groundwork need to be laid first. But now that it
> was mentioned in another thread, I think it is a good idea to show it,
> to see how people like it.
>

+1. I assume a lot of the AVDocNode can be automatically populated from its
corresponding option? We'd not want to maintain, e.g. option names and
aliases in more than one place.

Cheers,
Dee
___
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel

To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".

[FFmpeg-devel] Embedded documentation?

[Nicolas George]

Hi.

Three years ago, I shared some brief thoughts about embedding the
documentation in the libraries. For example, that would allow GUI
applications to open help dialogs about specific options.

To see what it would need, I wrote the following header. I did not work
any further, because groundwork need to be laid first. But now that it
was mentioned in another thread, I think it is a good idea to show it,
to see how people like it.

Please share your remarks. Even “+1” to say you like it, because people
who will not like it will not hesitate to post “-1”.

Regards,

-- 
  Nicolas George
typedef struct AVDocNode AVDocNode;
typedef struct AVDocLink AVDocLink;
typedef enum AVDocNodeType AVDocNodeType;
typedef enum AVDocLinkType AVDocLinkType;

/**
 * Link to another documentation node.
 */
struct AVDocLink {
AVDocNode *target;
AVDocLinkType type;
};

/**
 * Node in the documentation system.
 *
 * A node can be the description of a codec, format, filter, option, type,
 * etc.
 */
struct AVDocNode {

/**
 * Names of the component.
 *
 * It is a concatenation of 0-terminated strings, terminated by an empty
 * string (i.e. a double 0).
 * For example "frame_rate, rate, r" would be "frame_rate\0rate\0r\0\0".
 * The first name is the main name of the component, the other are
 * aliases.
 * If this field is used as a plain C string, it contains only the main
 * name.
 */
const char *names;

/**
 * Unique identifier of the compnent.
 *
 * It is composed of alphanumeric characters plus underscore and slash
 * and written hierarchically.
 *
 * For example, the width option of the scale filter would be
 * "lavfi/vf_scale/opt_width".
 *
 * This identifier can be used for links in the text.
 *
 * It matches the symbol that makes the documentation available, in the
 * avdoc_ namespace with double underscore standing for slashes:
 * extern const AVDocNode avdoc_lavfi__vf_scale__opt_width;
 */
const char *id;

/**
 * Title / short description, possibly NULL.
 *
 * Can be used in a table of contents for example.
 */
const char *title;

/**
 * Text of the documentation in XXX Markdown / FFHTML.
 *
 * Apparently we want to write the documentation in Markdown or similar,
 * but the build system can convert when creating the data structure to
 * embed in the library.
 *
 * On one hand, Markdown can be dumped as is to the user, in a terminal
 * or a basic dialog box.
 *
 * On the other hand, strict minimalist HTML is more program-friendly,
 * which makes it more convenient for programs that want to display it
 * with actual italics 
 *
 * I think FFHTML (i.e. a small, strict and clearly documented subset of
 * HTML) would be better.
 */
const char *text;

/**
 * Object about which the documentation is.
 *
 * If not NULL, points to an object starting with an AVClass pointer.
 */
void *object;

/**
 * Links towards other nodes.
 *
 * All nodes linked in the text must have an entry here, but implicit
 * links are possible too, for example the type of an option.
 *
 * The types are ordered by type.
 */
const AVDocLink *links;

/**
 * Type of the node, and of the object documented.
 */
AVDocNodeType type;

};

/**
 * Type of a documentation node.
 */
enum AVDocNodeType {
AVDOC_TYPE_GENERIC = 0,
AVDOC_TYPE_MUXER,
AVDOC_TYPE_DEMUXER,
AVDOC_TYPE_ENCODER,
AVDOC_TYPE_DECODER,
AVDOC_TYPE_FILTER,
AVDOC_TYPE_BITSTREAM_FILTER,
AVDOC_TYPE_SWSCALER,
AVDOC_TYPE_SWRESAMPLER,
AVDOC_TYPE_DEVICE_VIDEO_OUTPUT,
AVDOC_TYPE_DEVICE_VIDEO_INPUT,
AVDOC_TYPE_DEVICE_AUDIO_OUTPUT,
AVDOC_TYPE_DEVICE_AUDIO_INPUT,
AVDOC_TYPE_DEVICE_OUTPUT,
AVDOC_TYPE_DEVICE_INPUT,
AVDOC_TYPE_OPTION,
AVDOC_TYPE_TYPE,
AVDOC_TYPE_SYNTAX,
AVDOC_TYPE_EXAMPLES,
AVDOC_TYPE_EXPLANATIONS,
};

/**
 * Type of a link, i.e. relation between the source and the target of the
 * link.
 *
 * More important links have a lower value.
 */
enum AVDocLinkType {

/**
 * The linked node is the parent.
 *
 * For example, the parent the node for a private option is the node for
 * the corresponding codec/format/filter.
 */
AVDOC_LINK_PARENT = 0x100,

/**
 * The linked node is a subpart, section, chapter, etc.
 */
AVDOC_LINK_SUBPART = 0x200,

/**
 * The linked node describes an option or an option constant.
 */
AVDOC_LINK_OPTION = 0x300,

/**
 * Threshold value for the self-contained minimal documentation of an
 * object.
 */
AVDOC_LINK_SELF_CONTAINED = 0x400,

/**
 * The linked node is the reference for a type, syntax, etc.
 */
AVDOC_LINK_REFERENCE = 0x500,

/**
 * Threshold value for the self-contained complete documentation of an