Copy: ulm@gentoo.org (Ulrich Mueller)
Copy: sam@gentoo.org (Sam James)
Copy: flow@gentoo.org (Florian Schmaus)

This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --------------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.html
--
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 cjEuZWNsYXNzCmx1YS5lY2xhc3MKbHVhLXNpbmdsZS