[gentoo-dev] merging man page documentation into eclasses

[gentoo-dev] merging man page documentation into eclasses

[Mike Frysinger]

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

keeping documentation of functions in a separate file (man pages in this case) 
has obvious bit rot problems written all over it, so i'd like to merge the 
documentation into the respective eclasses so that the man pages can be 
automatically generated

off the cuff, i'd propose a style like:
# FUNCTION: edos2unix
# USAGE: <files>
# DESCRIPTION:
# A handy replacement for dos2unix, recode, fixdos, etc...  This allows you
# to remove all of these text utilities from DEPEND variables because this
# is a script based solution.  Just give it a list of files to convert and
# they will all be changed from the DOS CRLF format to the UNIX LF format.
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 827 bytes --]

Re: [gentoo-dev] merging man page documentation into eclasses

[Andrew Ross]

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

Mike Frysinger wrote:
> keeping documentation of functions in a separate file (man pages in this case) 
> has obvious bit rot problems written all over it, so i'd like to merge the 
> documentation into the respective eclasses so that the man pages can be 
> automatically generated

+1

Of course, I always use the eclass itself for reference (since not all
eclasses have man pages).

Cheers

Andrew


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 249 bytes --]

Re: [gentoo-dev] merging man page documentation into eclasses

[Joshua Nichols]

Mike Frysinger wrote:
> keeping documentation of functions in a separate file (man pages in this case) 
> has obvious bit rot problems written all over it, so i'd like to merge the 
> documentation into the respective eclasses so that the man pages can be 
> automatically generated
>   

For the Java eclasses, we've been marking them up with something akin to
javadoc. We never did get around to writting something that actually
parses it though, but I wouldn't imagine it to be difficult.

 See java-utils-2.eclass for what it looks like.

-- 
Joshua Nichols
Gentoo/Java Secondary Project Lead
Gentoo/Xfce Project Lead
Gentoo/Ruby Developer

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] merging man page documentation into eclasses

[Mike Frysinger]

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

On Monday 11 June 2007, Mike Frysinger wrote:
> keeping documentation of functions in a separate file (man pages in this
> case) has obvious bit rot problems written all over it, so i'd like to
> merge the documentation into the respective eclasses so that the man pages
> can be automatically generated

ive added docs to eutils.eclass and you can find the awk script in 
app-portage/eclass-manpages/files/eclass-to-manpage.awk for people who want 
to review
-mike

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 827 bytes --]