[FFmpeg-devel] Embedded documentation?

* [FFmpeg-devel] Embedded documentation?
@ 2023-05-01 10:13 Nicolas George
  2023-05-01 11:28 ` Diederick C. Niehorster
                   ` (3 more replies)
  0 siblings, 4 replies; 12+ messages in thread
From: Nicolas George @ 2023-05-01 10:13 UTC (permalink / raw)
  To: ffmpeg-devel

[-- Attachment #1.1.1: Type: text/plain, Size: 621 bytes --]

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

[-- Attachment #1.1.2: documentation.c --]
[-- Type: text/x-csrc, Size: 6849 bytes --]

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
     * object, including refernce for types and syntaxes.
     */
    AVDOC_LINK_SELF_CONTAINED_FULL = 0x600,

    /**
     * The linked node contains details and explanations.
     */
    AVDOC_LINK_DETAILS = 0x700,

};

typedef struct AVDocExcerpt AVDocExcerpt;
typedef struct AVDocTocNode AVDocTocNode;

/**
 * Excerpt of the documentation, structured and with links.
 *
 * Always returned by the library.
 *
 * This structure is the root of a tree of AVDocTocNode;
 * siblings in the tree are structured as a linked list.
 */
struct AVDocExcerpt {

    /**
     * First node of the excerpt
     */
    AVDocTocNode *begin;

};

/**
 * Node in an excerpt of the documentation.
 *
 * This contains the node and its relation with other nodes.
 */
struct AVDocTocNode {

    AVDocNode *node;

    AVDocTocNode *next;

    AVDocTocNode *first_child;

};

/**
 * Get the documentation node associated with an object, if any.
 *
 * obj must point to an object starting with an AVClass pointer.
 */
const AVDocNode *av_documentation_get_node(void *obj);

/**
 * Get an excerpt of the documentation around a node.
 *
 * @param excerpt    used to return the excerpt
 * @param nodes      nodes to document;
 *                   if one is NULL, it is skipped;
 *                   if all are NULL, a dummy documentation is returned
 * @param nb_nodes   number of nodes
 * @param threshold  limit of the excerpt, it will contain all nodes pointed
 *                   by links that are below the threshold, recursively;
 *                   AVDOC_LINK_SELF_CONTAINED and
 *                   AVDOC_LINK_SELF_CONTAINED_FULL are useful values.
 * @return  >= 0 for success or an AVERROR code, possibly AVERROR(ENOMEM)
 */
int av_documentation_get_excerpt(AVDocExcerpt **excerpt,
                                 const AVDocNode **node, unsigned nb_nodes,
                                 AVDocLinkType threshold);

typedef enum AVDocFormat {
    AV_DOC_FORMAT_HTML,
    AV_DOC_FORMAT_MARKDOWN,
};

#define AV_DOC_FORMAT_FLAG_TOC 0x0001

/**
 * Serialize a documentation excerpt.
 */
void av_documentation_write(AVWriter wr, AVDocExcerpt **excerpt,
                            AVDocFormat format, unsigned flags);

[-- Attachment #1.2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[-- Attachment #2: Type: text/plain, Size: 251 bytes --]

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

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

^ permalink raw reply	[flat|nested] 12+ messages in thread