Created attachment 280591 [details, diff] Adds @SEE_ALSO to eclass-to-manpage.awk Currently the SEE ALSO section contains only ebuild(5), it would be nice to have a means to add inherited eclasses there as well. A simple solution could be an @SEE_ALSO: <optional; list of eclass names> Attached is a possible implementation thereof. Thanks.
seems like we should be able to auto-calculate this ourselves from the "inherited" line ... but we'll probably still want @SEE_ALSO so people can list "parallel" eclasses like linux-info and linux-mod, or the diff kde eclasses ...
One of the issue with extracting inherit is that the target eclass might not have a man page. Arguably a QA issue though. Then there are the eclasses which are only meant to be used by other eclasses. So maybe @SEE_ALSO: <optional:...> would best be implemented as top level marker. The awk script would then only extract the eclasses in the directly following inherit line. Anyway, a user can already do what he needs with the @SEE_ALSO: alone. So extracting becomes the cherry on the cake.
i'm not worried about man pages not existing
Created attachment 280853 [details, diff] This patch is supposed to allow converting java eclasses The java eclasses currently use an own sophisticated documentation language. Kind of overkill. Still a certain subset of features would be nice to have. I spent most of the weekend documenting java eclasses and extending eclass-manpages where I felt it was necessary. The patch covers this work. The patch can't be applied straight away. All eclass-variables would end up in the POST INHERIT sub section. Not a big issue but people would need to be informed beforehand. I implemented @SEE_ALSO in a slightly different and better way as the earlier patch does. The patch also covers @PREINHERIT @SECTION @EXPORTED I have added @AUTHOR as it was mentioned in the source already and seemed reasonable. I intend to write a page for the devmanual later, if this is something which people would want. Please let me know what you think of the patch and the ideas it contains.
i merged the @AUTHOR support with slight modifications since some eclass people are cramming this in there even without it. might as well standardize it and not let people do whatever they feel like. http://sources.gentoo.org/app-portage/eclass-manpages/files/eclass-to-manpage.awk?r1=1.22&r2=1.23
Created attachment 284979 [details, diff] Possible enhancements for eclass-manpages Updated patch with all proposed enhancements, accounting for recent changes. New: add support for @DEPRECATED; tag can be found in qt4.eclass for instance.
Created attachment 284983 [details] Basic draft for a dev-manual page. This is a minimal draft for a dev-manual page. It certainly needs to be reworked later based on the actual implementation. If there are issues with the content let me know.
Comment on attachment 284983 [details] Basic draft for a dev-manual page. the problem with this is keeping the two in sync. i keep the comments at the top of eclass-to-manpage.awk up-to-date since that's the file implementing the spec. so there really needs to be a way to automatically the two.
@DEPRECATED: https://github.com/projg2/eclass-to-manpage/commit/1911b68dbdc2bc49e577616b5b5080f55348de54 The rest is going to be handled via the pmaint support for eclass docs which Arthur is working on (https://github.com/pkgcore/pkgcore/pull/346).
