1 |
Hi, |
2 |
|
3 |
I've written nascent support for eclassdoc man page generation (along |
4 |
with rST and HTML docs) in pkgcore [1] accessible on the cli via `pmaint |
5 |
eclass` that intends to provide an alternative to the current awk |
6 |
implementation [2]. |
7 |
|
8 |
In doing so, I've noticed that the formatting of the docs feels quite |
9 |
haphazard due to reinventing some of the syntax for proper markup |
10 |
languages via embedded tags (e.g. @CODE for literal code blocks) while |
11 |
not handling other basic cases properly (e.g. bulleted lists). |
12 |
|
13 |
What does the community think about selecting a specific markup language |
14 |
and using that for multiline text for related eclassdoc tags (e.g. |
15 |
@DESCRIPTION)? That way, we can toss out the @CODE/@SUBSECTION tag |
16 |
workarounds and use what the markup language natively provides directly. |
17 |
|
18 |
In terms of choice, I'd personally choose reStructuredText since that |
19 |
generally plugs into python easier via docutils/sphinx (currently used |
20 |
for pkgcore's man/html conversion), but am open to discussion of |
21 |
alternatives such as markdown. |
22 |
|
23 |
The downside of moving to an actual markup language is that writing docs |
24 |
for eclasses will get stricter, but conversion issues could be flagged |
25 |
by pkgcheck aiding verification. |
26 |
|
27 |
Thanks, |
28 |
Tim |
29 |
|
30 |
[1]: https://github.com/pkgcore/pkgcore/commit/b3a6b8da |
31 |
[2]: https://github.com/mgorny/eclass-to-manpage/blob/master/eclass-to-manpage.awk |