[gentoo-dev] using markup language for eclassdoc tags

[gentoo-dev] using markup language for eclassdoc tags

[Tim Harder]

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.

The downside of moving to an actual markup language is that writing docs
for eclasses will get stricter, but conversion issues could be flagged
by pkgcheck aiding verification.

Thanks,
Tim

[1]: https://github.com/pkgcore/pkgcore/commit/b3a6b8da
[2]: https://github.com/mgorny/eclass-to-manpage/blob/master/eclass-to-manpage.awk

Re: [gentoo-dev] using markup language for eclassdoc tags

[Michał Górny]

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

Re: [gentoo-dev] using markup language for eclassdoc tags

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 728 bytes --]

>>>>> On Mon, 04 Jan 2021, Tim Harder wrote:

> 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.

About reStructuredText vs Markdown:
- ReST syntax is more complete and better standardised.
- Markdown uses HTML as extension language, which is fine when
  converting to HTML but makes conversion to other formats more
  difficult.
- Trailing whitespace as part of Markdown's syntax is problematic
  (and the current version of app-emacs/ebuild-mode removes it).
- We already use ReST for some of our documentation, like GLEPs.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]

Re: [gentoo-dev] using markup language for eclassdoc tags

[Tim Harder]

On 2021-01-04 Mon 04:18, Michał Górny wrote:
> 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.

The existing syntax is supported by the current work that just uses
literal blocks for all multiline text fields. This attempts avoiding all
the semi-formatting issues, the downside being that text flow across
paragraphs is broken since all the formatting is preserved as written in
the eclasses.

Pivoting to an actual markup language will be trivial if/when that
occurs.

Tim