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 76E884617A for ; Mon, 8 May 2023 15:43:07 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 2610768C1B7; Mon, 8 May 2023 18:43:04 +0300 (EEST) Received: from nef.ens.fr (nef2.ens.fr [129.199.96.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 86FBB68C148 for ; Mon, 8 May 2023 18:42:57 +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 348Fgua8024198 for ; Mon, 8 May 2023 17:42:57 +0200 Received: by phare.normalesup.org (Postfix, from userid 1001) id AE9E7EB5BF; Mon, 8 May 2023 17:42:56 +0200 (CEST) Date: Mon, 8 May 2023 17:42:56 +0200 From: Nicolas George To: FFmpeg development discussions and patches Message-ID: References: <20230507221033.GC4348@mariano> MIME-Version: 1.0 In-Reply-To: <20230507221033.GC4348@mariano> X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (nef.ens.fr [129.199.96.32]); Mon, 08 May 2023 17:42:57 +0200 (CEST) Subject: Re: [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="===============4672669477038448712==" Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: --===============4672669477038448712== Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="Z76CZbaczoppTt7k" Content-Disposition: inline --Z76CZbaczoppTt7k Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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 =E2=80=9Cgive me t= he documentation for this=E2=80=9D 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, --=20 Nicolas George --Z76CZbaczoppTt7k Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEE6ooRQGBoNzw0KnwPcZVLI8pNxgwFAmRZGH4ACgkQcZVLI8pN xgxmmg/+KXyCsH+viT3wfaC+mTqmA2aqF5SNbCx+7yDOlHN8msXeilDr1YlsVNx/ s/e/9++4aR+RBvXhXm4GQG5VF8RLIwy/G+p4xrynJ9ojJgPCjlhiY+1FyWntBEs6 3TjRMbETmzQpszsaVaLI/XR+PgwhHVMZ2fMMuMwOo3omNHKbif+IXBmnya2mVd6R XrH/EG5l0K51x4qA36xetZHTQdLOphMJjKg3JT/a6WX6larQ/7+uSWP/cVZALhqr 8DYUBxLsLgL+tqSwmIcn875ja7HhZ946cNYFunjhMTnTUu8b6yCKAoNMXjPlkvId kNkaEdKSo1AnCRkhPLBo8fSS+fXtKZ8MdxeiM4fCpplCHWQC0PHOu3KtbVPZAFl4 0bRMyGU0CCkDuxCYDqQ/LNZrxUcrqe22A+2ZdpBvt1MA3QiB7iVaEXptg5J2QxdW SMY2UQZX66Nb+TTXcIBs9xTCJc0c5HuQpVAfiCRclSc1yBY/+K7se/pmffZylehe 7RRrckfIu7uksK6fxjuSYz2gLoqDc19cDHCRVLMWfpnKvoOt70Sw+e4EprzWIlre JiQ70IDzLKgwrCliZ97B5zDmN+95X38ZbpuYjj5tg7Qq1XrkrPr2WqhXrj1qV+pn i8O+i5E4yKL6B5GmbffEc/9PYd3UoZP+MRNdGvWMJfeOuxZ1V2o= =3mzg -----END PGP SIGNATURE----- --Z76CZbaczoppTt7k-- --===============4672669477038448712== 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". --===============4672669477038448712==--