Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 202656 - Provide a way to generate eclass documentation for devmanual
Summary: Provide a way to generate eclass documentation for devmanual
Status: RESOLVED FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Devmanual (show other bugs)
Hardware: All Linux
: High normal (vote)
Assignee: Jeremy Olexa (darkside) (RETIRED)
URL:
Whiteboard:
Keywords:
Depends on:
Blocks: 177778
  Show dependency tree
 
Reported: 2007-12-18 07:57 UTC by SpanKY
Modified: 2011-02-17 22:00 UTC (History)
3 users (show)

See Also:
Package list:
Runtime testing required: ---


Attachments
sed script to convert .eclass files to devmanual compatible pages (devmanual-eclass.sed,1.99 KB, text/plain)
2008-08-27 22:33 UTC, Boian Berberov
Details

Note You need to log in before you can comment on or make changes to this bug.
Description SpanKY gentoo-dev 2007-12-18 07:57:35 UTC
the eclass documentation should be totally scrapped:
http://devmanual.gentoo.org/eclass-reference/index.html

eclasses can (and should) be self-documenting now via the eclass-manpages package

if we want pretty web pages (rather than man pages), then i'd suggest someone put together an awk to auto-generate it from eclasses and output into guidexml rather than the devmanual
Comment 1 Mark Loeser (RETIRED) gentoo-dev 2007-12-18 22:17:12 UTC
I'll look into what would be required to auto-generate them so the eclass documentation fits in like it does now.
Comment 2 SpanKY gentoo-dev 2007-12-19 00:07:26 UTC
i was suggesting scrapping as part of the unification of disparate manuals

make the autogeneration output integrate into guidexml, not devmanual ... one less thing to convert later
Comment 3 Ciaran McCreesh 2007-12-19 00:12:17 UTC
Converting man pages into devmanual is a heck of a lot easier than converting devmanual into guidexml (devmanual needs a huge number of guidexml extensions which probably won't ever happen).
Comment 4 SpanKY gentoo-dev 2007-12-19 00:18:42 UTC
no one is talking about converting man pages.  in fact, i say quite the opposite in the original comment.

expanding on guidexml is a possibility.  devmanual should go away.
Comment 5 Ciaran McCreesh 2007-12-19 00:22:50 UTC
Which is all very nice in theory, but in practice the reason devmanual didn't use guidexml still stands: it's a huge amount of effort. For practical reasons, the way the devmanual is currently is the only way it's going to work until someone with a lot of spare time and enough patience to deal with XSLT comes along and puts in the work.
Comment 6 SpanKY gentoo-dev 2007-12-19 01:04:22 UTC
well it's a good thing we a QA team to work on that sort of thing
Comment 7 Mark Loeser (RETIRED) gentoo-dev 2007-12-19 01:05:26 UTC
(In reply to comment #6)
> well it's a good thing we a QA team to work on that sort of thing
> 

We do?
Comment 8 Ciaran McCreesh 2007-12-19 01:06:46 UTC
I was under the impression that Gentoo had barely enough of the QA team to keep up with the basics, and that converting a large document to and maintaining a large document in a rather inconvenient format was substantially beyond its current capabilities.

But if I'm wrong there, then yes, switching to guidexml is the way to go.
Comment 9 SpanKY gentoo-dev 2007-12-19 01:36:08 UTC
if that's true, then the people doing nothing should make way for the people doing the work
Comment 10 Ciaran McCreesh 2007-12-19 01:42:35 UTC
By not making requests that they spend all their time messing around with impractical formats and changing things for aesthetic reasons?
Comment 11 SpanKY gentoo-dev 2007-12-19 01:49:12 UTC
i'm not sure what requests you're referring to, but that certainly has nothing to do with this
Comment 12 Mark Loeser (RETIRED) gentoo-dev 2008-05-19 01:44:41 UTC
Updating summary
Comment 13 Boian Berberov 2008-08-27 22:33:56 UTC
Created attachment 163942 [details]
sed script to convert .eclass files to devmanual compatible pages

I stumbled on this bug and I wrote this sed script.  Apply with the --quiet option.  If this is what you are looking for, I can work on improving the script to do what needs to be done.
Comment 14 Jeremy Olexa (darkside) (RETIRED) archtester gentoo-dev Security 2010-08-10 15:13:07 UTC
(In reply to comment #13)
> Created an attachment (id=163942) [details]
> sed script to convert .eclass files to devmanual compatible pages
> 
> I stumbled on this bug and I wrote this sed script.  Apply with the --quiet
> option.  If this is what you are looking for, I can work on improving the
> script to do what needs to be done.
> 

It is good, but not perfect. It doesn't output VARIABLES, only functions.
Here is my test: http://devmanual.gentoo.org/eclass-reference/xfconf.eclass/index.html (not linked from anywhere yet)
Comment 15 Jeremy Olexa (darkside) (RETIRED) archtester gentoo-dev Security 2010-08-10 16:09:23 UTC
(In reply to comment #14)
> (In reply to comment #13)
> > Created an attachment (id=163942) [details] [details]
> > sed script to convert .eclass files to devmanual compatible pages
> > 
> > I stumbled on this bug and I wrote this sed script.  Apply with the --quiet
> > option.  If this is what you are looking for, I can work on improving the
> > script to do what needs to be done.
> > 
> 
> It is good, but not perfect. It doesn't output VARIABLES, only functions.
> Here is my test:
> http://devmanual.gentoo.org/eclass-reference/xfconf.eclass/index.html (not
> linked from anywhere yet)

Scrap that. I'm going to use eclass-manpages and man2html to skip the xml step. Re-assigning to myself and will update this bug when complete.

New proto: http://devmanual.gentoo.org/eclass-reference/xorg-2.eclass/index.html
Comment 16 Jeremy Olexa (darkside) (RETIRED) archtester gentoo-dev Security 2011-02-03 17:09:12 UTC
FYI, this is completed. Sadly, I have not investigated a way to add the link to the main page. Generated daily: http://devmanual.gentoo.org/eclass-reference/index.html
Comment 17 Jeremy Olexa (darkside) (RETIRED) archtester gentoo-dev Security 2011-02-17 22:00:45 UTC
There is now a link to "Eclass Reference Pages" on the main index.html. Fixed on the server-side script that runs the Makefile.