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