From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from ffbox0-bg.mplayerhq.hu (ffbox0-bg.ffmpeg.org [79.124.17.100]) by master.gitmailbox.com (Postfix) with ESMTP id 4035046032 for ; Mon, 1 May 2023 10:13:18 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 4824168BF55; Mon, 1 May 2023 13:13:16 +0300 (EEST) Received: from nef.ens.fr (nef2.ens.fr [129.199.96.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id D377A68BF41 for ; Mon, 1 May 2023 13:13:09 +0300 (EEST) X-ENS-nef-client: 129.199.129.80 ( name = phare.normalesup.org ) Received: from phare.normalesup.org (phare.normalesup.org [129.199.129.80]) by nef.ens.fr (8.14.4/1.01.28121999) with ESMTP id 341AD9PH021022 for ; Mon, 1 May 2023 12:13:09 +0200 Received: by phare.normalesup.org (Postfix, from userid 1001) id 1526AEB5BF; Mon, 1 May 2023 12:13:09 +0200 (CEST) Date: Mon, 1 May 2023 12:13:09 +0200 From: Nicolas George To: ffmpeg-devel@ffmpeg.org Message-ID: MIME-Version: 1.0 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (nef.ens.fr [129.199.96.32]); Mon, 01 May 2023 12:13:09 +0200 (CEST) Subject: [FFmpeg-devel] Embedded documentation? X-BeenThere: ffmpeg-devel@ffmpeg.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: FFmpeg development discussions and patches List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: FFmpeg development discussions and patches Content-Type: multipart/mixed; boundary="===============1233138565042833708==" Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: --===============1233138565042833708== Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="CkJ7vRpleKcv2W+p" Content-Disposition: inline --CkJ7vRpleKcv2W+p Content-Type: multipart/mixed; boundary="by1vFuE5R+nl/d+5" Content-Disposition: inline --by1vFuE5R+nl/d+5 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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 =E2=80=9C+1=E2=80=9D to say you like it, be= cause people who will not like it will not hesitate to post =E2=80=9C-1=E2=80=9D. Regards, --=20 Nicolas George --by1vFuE5R+nl/d+5 Content-Type: text/x-csrc; charset=us-ascii Content-Disposition: attachment; filename="documentation.c" Content-Transfer-Encoding: quoted-printable 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=20 * * 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 =3D 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 =3D 0x100, /** * The linked node is a subpart, section, chapter, etc. */ AVDOC_LINK_SUBPART =3D 0x200, /** * The linked node describes an option or an option constant. */ AVDOC_LINK_OPTION =3D 0x300, /** * Threshold value for the self-contained minimal documentation of an * object. */ AVDOC_LINK_SELF_CONTAINED =3D 0x400, /** * The linked node is the reference for a type, syntax, etc. */ AVDOC_LINK_REFERENCE =3D 0x500, /** * Threshold value for the self-contained complete documentation of an * object, including refernce for types and syntaxes. */ AVDOC_LINK_SELF_CONTAINED_FULL =3D 0x600, /** * The linked node contains details and explanations. */ AVDOC_LINK_DETAILS =3D 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 >=3D 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); --by1vFuE5R+nl/d+5-- --CkJ7vRpleKcv2W+p Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEE6ooRQGBoNzw0KnwPcZVLI8pNxgwFAmRPkLIACgkQcZVLI8pN xgzDBhAAo6IOmt3/oXNzUV+oUXJ84Ky3hig9wpKXblSm3MebGmx4aEHOF36FVMXU wy4s7QBFJ5NKsldwVsZ+fCPdQj5LkDEEUAgagb2fr5BXbMkglQzjwsOe3/Q1iLsB +7B3J4chpJ6Uf1MdaUvuPYuWk8tm8AHbYWMyvmuDmxIkdoqiRd3kIUXi8dzniyhv +0fZV4T4/WtIuYh/BvmL298GyTOxeUaLcHfWgWNjGt1Pw87bb3rXc4apXX+J6axf Jjg7t6O+mnHZkRVaSqf6s1gyMRdsUuSF9UL9Bg7iXW7wxivZJW0mtrfC8/sI/4HK 5LaKHrSQ4I8CWc64Bq7FcffcckNsY/rlbIzU1BQlHCscGORTVgVgqXiU5bylo1BV zTwtnTTe6sA0Fb8JkNsdYweTsnwDh4vrVnWx+kIhfh+Yyv4lw+WPuRQDGpl9ejao 1r6U46UTTv5SR3lSdPUqELtP4ItlJ58MBFp7PF6EYEOIMXUruaMkoL6sT8Y1qYJG 9JozKf7Nv41BHkyPpQhHJBUz40xBl5z63Z8aoRUddTCjaNMHXTJE5wf7QheNxvIU xjKNQCswCMKMIDNuf/a25KZ7clANn3ORCxc2KwndI4x+5Gk9QswS680uzPGENkAD gjoMM8xcpOTp3xXrTBxxFyZfQX7QF1vzXlca0RhyjBcIhYl9oaQ= =W9nt -----END PGP SIGNATURE----- --CkJ7vRpleKcv2W+p-- --===============1233138565042833708== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ 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". --===============1233138565042833708==--