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)