On Mon, 2021-01-04 at 04:03 -0700, Tim Harder wrote: > Hi, > > I've written nascent support for eclassdoc man page generation (along > with rST and HTML docs) in pkgcore [1] accessible on the cli via `pmaint > eclass` that intends to provide an alternative to the current awk > implementation [2]. > > In doing so, I've noticed that the formatting of the docs feels quite > haphazard due to reinventing some of the syntax for proper markup > languages via embedded tags (e.g. @CODE for literal code blocks) while > not handling other basic cases properly (e.g. bulleted lists). > > What does the community think about selecting a specific markup language > and using that for multiline text for related eclassdoc tags (e.g. > @DESCRIPTION)? That way, we can toss out the @CODE/@SUBSECTION tag > workarounds and use what the markup language natively provides directly. > > In terms of choice, I'd personally choose reStructuredText since that > generally plugs into python easier via docutils/sphinx (currently used > for pkgcore's man/html conversion), but am open to discussion of > alternatives such as markdown.
I'm all for switching to rST in the foreseeable future but let's stick with the existing syntax for the transition period, i.e. until new pkgcore is stable and deployed on Infra. I'm not saying you have to strictly copy the existing magic, just get a reasonably readable result for the existing eclasses. -- Best regards, Michał Górny
