From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id DB45B158089 for ; Mon, 23 Oct 2023 17:56:04 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 7BAEB2BC01A; Mon, 23 Oct 2023 17:56:00 +0000 (UTC) Received: from smtp.gentoo.org (woodpecker.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 44FCB2BC013 for ; Mon, 23 Oct 2023 17:56:00 +0000 (UTC) Message-ID: <03c05c03-f1f2-44bf-b429-81ae20aea9fd@gentoo.org> Date: Mon, 23 Oct 2023 20:55:37 +0300 Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply MIME-Version: 1.0 User-Agent: Mozilla Thunderbird Content-Language: en-US To: gentoo-dev@lists.gentoo.org Cc: Ulrich Mueller , Sam James , Florian Schmaus From: Arthur Zamarin Subject: [gentoo-dev] Using RST for eclassdoc Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="------------oUTRbN6CIWmjaCQsHu6Ikny9" X-Archives-Salt: d2cbfedd-47ce-49c6-bd9e-d0b71c0ae837 X-Archives-Hash: b12a3093642e41aa743b7d40efff1f9c This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------oUTRbN6CIWmjaCQsHu6Ikny9 Content-Type: multipart/mixed; boundary="------------CI1gX7n5eYBdAkZZYrowpYjH"; protected-headers="v1" From: Arthur Zamarin Reply-To: gentoo-dev@lists.gentoo.org To: gentoo-dev@lists.gentoo.org Cc: Ulrich Mueller , Sam James , Florian Schmaus Message-ID: <03c05c03-f1f2-44bf-b429-81ae20aea9fd@gentoo.org> Subject: Using RST for eclassdoc --------------CI1gX7n5eYBdAkZZYrowpYjH Content-Type: multipart/mixed; boundary="------------1hUPs2m0yYtB41zhmJnVL3s5" --------------1hUPs2m0yYtB41zhmJnVL3s5 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Hi all For a very long time, we had a WIP branch for pkgcore [1], where I tried to implement parsing of eclassdoc, and convert them to devbook (the format used by devmanual), which the devmanual [2] then would convert to html using the normal converter used there. So, why was this wanted and what happened since? ------------ History ------------ Our eclassdocs consist of special tags (such as "@INTERNAL" and "@DESCRIPTION") which represent various information. The free-text part is without real rules on formattinf, meaning we can't really say "this is code", "bold this text", "this is a numeric list", "this is bullet list". We have used various hacks and stuff, and it worked mostly. There was a complicated tool which converted those eclassdoc into man page, and then the man page was converted to html. On 2022-05, I was requested to investigate the possibility of using pkgcore for preparing those files, with selection of RST as the formatting syntax. I've managed to do it and it worked, with also a possibility for pkgcore generating the man pages. But as expected, we had various eclasses whose eclassdoc wasn't exactly matching, and also various eclass' format could be improved. I've worked on it at the PR [3], but for the huge take of verifying all eclasses, I tired it out. Yes, this was a mistake on my part. To see the state where we can get and why, look at my devspace [4] to see the result for the very old PR [3]. --------- Current state --------- I've merged into pkgcore the devbook code generator. You need pkgcore-9999 for that. You need my changes to the build of devmanual at [2]. We need to declare that from now on eclassdoc uses RST format, so at least future changes would not break us. I'll again say that RST isn't too far from what we used today, so this isn't a big change. Maybe this should be put in a GLEP? We need to fix the eclassdoc of the "broken eclasses". I've attached a file listed all of them. Just run `make` on the devmanual and you can see in the relevant eclass html file a warning box with the issue. Most of the time it is adding `` for marking it as code. [1] https://github.com/pkgcore/pkgcore/pull/346 [2] https://github.com/gentoo/devmanual/pull/317 [3] https://github.com/gentoo/gentoo/pull/27646 [4] https://dev.gentoo.org/~arthurzam/devmanual/eclass-reference/index.ht= ml --=20 Arthur Zamarin arthurzam@gentoo.org Gentoo Linux developer (Python, pkgcore stack, Arch Teams) --------------1hUPs2m0yYtB41zhmJnVL3s5 Content-Type: text/plain; charset=UTF-8; name="broken-eclassdoc.txt" Content-Disposition: attachment; filename="broken-eclassdoc.txt" Content-Transfer-Encoding: base64 YWx0ZXJuYXRpdmVzLmVjbGFzcwphcGFjaGUtMi5lY2xhc3MKYXBhY2hlLW1vZHVsZS5lY2xh c3MKYXV0b3Rvb2xzLmVjbGFzcwpiYXplbC5lY2xhc3MKY2hlY2stcmVxcy5lY2xhc3MKY21h a2UuZWNsYXNzCmNvbW1vbi1saXNwLTMuZWNsYXNzCmN2cy5lY2xhc3MKZGlzdHV0aWxzLXIx LmVjbGFzcwpkb3RuZXQtcGtnLmVjbGFzcwplbGlzcC5lY2xhc3MKZmxhZy1vLW1hdGljLmVj bGFzcwpnaGMtcGFja2FnZS5lY2xhc3MKZ2l0LXIzLmVjbGFzcwpnbm9tZTItdXRpbHMuZWNs YXNzCmdvbGFuZy12Y3Mtc25hcHNob3QuZWNsYXNzCmdvLW1vZHVsZS5lY2xhc3MKaGFza2Vs bC1jYWJhbC5lY2xhc3MKamF2YS1hbnQtMi5lY2xhc3MKamF2YS1vc2dpLmVjbGFzcwpqYXZh LXBrZy1zaW1wbGUuZWNsYXNzCmphdmEtdXRpbHMtMi5lY2xhc3MKa2VybmVsLWJ1aWxkLmVj bGFzcwpsYXRleC1wYWNrYWdlLmVjbGFzcwpsaW51eC1pbmZvLmVjbGFzcwpsaW51eC1tb2Qt cjEuZWNsYXNzCmx1YS5lY2xhc3MKbHVhLXNpbmdsZS5lY2xhc3MKbWF0ZS5lY2xhc3MKbWVy Y3VyaWFsLmVjbGFzcwptb3psaW5ndWFzLXYyLmVjbGFzcwptdWx0aWxpYi1idWlsZC5lY2xh c3MKcGF4LXV0aWxzLmVjbGFzcwpwZXJsLWZ1bmN0aW9ucy5lY2xhc3MKcGVybC1tb2R1bGUu ZWNsYXNzCnBvc3RncmVzLW11bHRpLmVjbGFzcwpwcmVmaXguZWNsYXNzCnB5dGhvbi1hbnkt cjEuZWNsYXNzCnB5dGhvbi1yMS5lY2xhc3MKcHl0aG9uLXNpbmdsZS1yMS5lY2xhc3MKcXQ2 LWJ1aWxkLmVjbGFzcwpydWJ5LW5nLmVjbGFzcwpydWJ5LXNpbmdsZS5lY2xhc3MKcnVzdC10 b29sY2hhaW4uZWNsYXNzCnNlY3VyZWJvb3QuZWNsYXNzCnN0YXJkaWN0LmVjbGFzcwpzdWJ2 ZXJzaW9uLmVjbGFzcwpzeXN0ZW1kLmVjbGFzcwp0b29sY2hhaW4tZnVuY3MuZWNsYXNzCnZl cmlmeS1zaWcuZWNsYXNzCnZlcnNpb25hdG9yLmVjbGFzcwp2aW0tc3BlbGwuZWNsYXNzCndl YmFwcC5lY2xhc3MKeGRnLXV0aWxzLmVjbGFzcwo= --------------1hUPs2m0yYtB41zhmJnVL3s5-- --------------CI1gX7n5eYBdAkZZYrowpYjH-- --------------oUTRbN6CIWmjaCQsHu6Ikny9 Content-Type: application/pgp-signature; name="OpenPGP_signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="OpenPGP_signature.asc" -----BEGIN PGP SIGNATURE----- iQEzBAEBCgAdFiEE/axFlFuH2ptjtO5EAqCvUD0SBQQFAmU2s5kACgkQAqCvUD0S BQRnHQgAplEN+jObfo69oYNlgetZ2McZD/tZeFxdg9YHvvw9AZsWY7m3Dxr100P+ IJEClh91HKGESNkOylGkIFjLVLbJDwVckJQGTz2rPoxC2Wy45Qiq9LTgWecJdl+M YsWeZnmB6iyeGxtbvRLYx/0IEbC0LbvbCRTBRBFcKYugw9Gca3FNiARYipqBYBHQ EDEMNzrkdGjyPM3a6oYpT0u1TYFfkJIYMbUOHRJaFgRfVFpyBx8QzwEL65P5XmuQ PqFgOyYB0vJ140tskST0puzaOs/01Bk14hpX9O4iDYNp4C68E82KfZ0DA9Ds5q7f 3iYagd22VwsurB5Sm5K0jIAy7eI84A== =Ri5t -----END PGP SIGNATURE----- --------------oUTRbN6CIWmjaCQsHu6Ikny9--