Gentoo Archives: gentoo-dev

From: Tim Harder <radhermit@g.o>
To: gentoo-dev@l.g.o
Subject: [gentoo-dev] using markup language for eclassdoc tags
Date: Mon, 04 Jan 2021 11:03:59
Message-Id: 20210104110352.GA11829@fir
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

Replies