* [gentoo-dev] tagging deprecated eclasses internally
@ 2020-09-24 0:06 Tim Harder
2020-09-26 11:23 ` Ulrich Mueller
0 siblings, 1 reply; 3+ messages in thread
From: Tim Harder @ 2020-09-24 0:06 UTC (permalink / raw
To: gentoo-dev
In short, pkgcheck (in git) now supports parsing the eclass doc format
as specified at [1] for the gentoo repo. This enables extracting more
info from various eclass doc annotations.
Along those lines, pkgcheck recognizes the '@DEPRECATED:' tag for all
eclass doc block types. At the global level, this allows deprecated
eclasses to internally document their status inside the '@ECLASS:'
block, note their replacement (if any), and add further information if
necessary.
This allows for the hardcoded and poorly maintained eclass deprecation
list in pkgcheck to be replaced by a dynamic version pulled from its
eclass cache.
If no one objects, I'd like to replace the deprecated-eclass section in
metadata/qa-policy.conf with individual '@DEPRECATED:' annotations for
the listed eclasses as well as adding info about the tag to the
devmanual.
Tim
[1]: https://devmanual.gentoo.org/eclass-writing/#documenting-eclasses
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [gentoo-dev] tagging deprecated eclasses internally
2020-09-24 0:06 [gentoo-dev] tagging deprecated eclasses internally Tim Harder
@ 2020-09-26 11:23 ` Ulrich Mueller
2020-10-10 20:58 ` Tim Harder
0 siblings, 1 reply; 3+ messages in thread
From: Ulrich Mueller @ 2020-09-26 11:23 UTC (permalink / raw
To: gentoo-dev
[-- Attachment #1: Type: text/plain, Size: 1266 bytes --]
>>>>> On Thu, 24 Sep 2020, Tim Harder wrote:
> In short, pkgcheck (in git) now supports parsing the eclass doc format
> as specified at [1] for the gentoo repo. This enables extracting more
> info from various eclass doc annotations.
> Along those lines, pkgcheck recognizes the '@DEPRECATED:' tag for all
> eclass doc block types. At the global level, this allows deprecated
> eclasses to internally document their status inside the '@ECLASS:'
> block, note their replacement (if any), and add further information if
> necessary.
> This allows for the hardcoded and poorly maintained eclass deprecation
> list in pkgcheck to be replaced by a dynamic version pulled from its
> eclass cache.
> If no one objects, I'd like to replace the deprecated-eclass section in
> metadata/qa-policy.conf with individual '@DEPRECATED:' annotations for
> the listed eclasses as well as adding info about the tag to the
> devmanual.
IIUC the authoritative document for eclass documentation is the
description of the format in the eclass-to-manpage.awk script, so this
would be a good start to add support for a new tag.
The devmanual only follows suit, and obviously cannot mention any tags
that aren't supported in man page conversion.
Ulrich
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 507 bytes --]
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [gentoo-dev] tagging deprecated eclasses internally
2020-09-26 11:23 ` Ulrich Mueller
@ 2020-10-10 20:58 ` Tim Harder
0 siblings, 0 replies; 3+ messages in thread
From: Tim Harder @ 2020-10-10 20:58 UTC (permalink / raw
To: gentoo-dev
On 2020-09-26 Sat 05:23, Ulrich Mueller wrote:
> IIUC the authoritative document for eclass documentation is the
> description of the format in the eclass-to-manpage.awk script, so this
> would be a good start to add support for a new tag.
Initial awk implementation available at [1], but currently only supports
showing eclass deprecation replacement/message even though all tag
groups are supported. I'm open to ideas for how variable/function
deprecation tag info should be formatted for manpages.
The tag syntax is currently the following:
# @DEPRECATED: <optional; replacement ("none" for no replacement)>
# <optional deprecation message>
This could be simplified to a single line if we want to force the usage
of @DESCRIPTION for additional deprecation info, but I think splitting
long deprecation info out is helpful.
[1]: https://github.com/mgorny/eclass-to-manpage/pull/4
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-10-10 20:58 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-09-24 0:06 [gentoo-dev] tagging deprecated eclasses internally Tim Harder
2020-09-26 11:23 ` Ulrich Mueller
2020-10-10 20:58 ` Tim Harder
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox