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 1668746177 for ; Mon, 8 May 2023 15:03:59 +0000 (UTC) Received: from [127.0.1.1] (localhost [127.0.0.1]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTP id 9647668C19F; Mon, 8 May 2023 18:03:56 +0300 (EEST) Received: from nef.ens.fr (nef2.ens.fr [129.199.96.40]) by ffbox0-bg.mplayerhq.hu (Postfix) with ESMTPS id 7CC1168C117 for ; Mon, 8 May 2023 18:03:50 +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 348F3mFh016801 for ; Mon, 8 May 2023 17:03:49 +0200 Received: by phare.normalesup.org (Postfix, from userid 1001) id D29D5EB5BF; Mon, 8 May 2023 17:03:48 +0200 (CEST) Date: Mon, 8 May 2023 17:03:48 +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:03:49 +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="===============2573038994583323269==" Errors-To: ffmpeg-devel-bounces@ffmpeg.org Sender: "ffmpeg-devel" Archived-At: List-Archive: List-Post: --===============2573038994583323269== Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="NZfUsD0RnmYgP3ck" Content-Disposition: inline --NZfUsD0RnmYgP3ck Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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 =E2=80=9Cit provides readable raw format=E2=80=9D: you seem to be a= ssuming 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 =E2=80=9C*=E2=80=9D and =E2=80=9C*= *=E2=80=9D. 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, --=20 Nicolas George --NZfUsD0RnmYgP3ck Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEE6ooRQGBoNzw0KnwPcZVLI8pNxgwFAmRZD1IACgkQcZVLI8pN xgyf+g/9EF2f8bnQRnxp8UW1qlCj1nD+tkuHmqduBZyJjXy2PAhEsQX1fj52qRSR 6I+aYDdCnJ6hGJRpb1osrE0ipF4onsX3vTiGPGXZVjjYbzNW47jWtLfVt01b1hoM jFnlwnH0mUrrtz7eX7js6ZCGpQD/Xc7inYf0cXet/0iFOa8BBv6AKZ1MOSRbHI2C ZP/ZfYXwBmmh5gdfvKgygxlraYdIPN0hxKBlOk5FQfQtRDiyjmJPMR6Q2/cOmQ68 0p4V9YC/yngLmOvnzV96eLydhUL3cjMJB2L0r7a4+wuSCnSmahwXlI3hDqkG8rBt qYaXWkHYxYAAyrd8V0qAnaiFnHxYnMG0rm3OMkYbV/ZRh+iGRG1EfapysFYwvDGR 9BUVuSzT5Z6NG5qMSHgAglhfwY/14NMum1iejh1Q3+OpLtWh4dgjY+9P92zZa53L VTdEwEmF9yqxRyT4QDJOc3Zd3XlZl7RhoorE0QrKCHhXpJ71h5qSWnCIRoSOg8M7 7CskeQ1cMQg8k+BDl4qTvRmUpPkEP41HY4Gr/jp8RWbWNCFY2LXVFVDCDGdBTxEO E5CPk2tOZBA6P6qFwe+OSKYWrg6+PHOT0+kJBaQbCc83omTjsHCAVsjLFrFFUG1X R4wlhKzg2jD/3fatfjuq6qR6V3FEPxUne718laK+/NL2QD4uNSA= =56DS -----END PGP SIGNATURE----- --NZfUsD0RnmYgP3ck-- --===============2573038994583323269== 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". --===============2573038994583323269==--