Pardus has asked for the wisdom of the Perl Monks concerning the following question:

Greetings oh wise monks,

I'm using pod files for a project's documentation and I was wondering: are there any tools to easily create indices of a directory tree with pod files ?

I noticed there the X<> tag in perlpod to mark topics for an index, but there is no reference to any tools which could use this.

I want to have a seperate index file with references to the indexed files. Of course one could just write an index.pod file, but it seems the L<> tag can't be used to create a simple relative link to a file in the same dir.

Anyone has tips or tricks for this ?
--
Jaap Karssenberg || Pardus (Larus)? <pardus@cpan.org>
>>>> Zoidberg: So many memories, so many strange fluids gushing out of patients' bodies.... <<<<

Replies are listed 'Best First'.
Re: index of pod files
by edoc (Chaplain) on May 13, 2003 at 00:18 UTC

    pods2html was what I settled on after trying quite a few different programs/modules that were meant to transverse directory trees. It's pretty damn cool, produces a TOC and you can specify your own style sheet that the pod docs will use. Not sure how it will go with the X<> and L<> tags, but definitely worth giving it a go.

    cheers,

    J

[reply]
Re: index of pod files
by crouchingpenguin (Priest) on May 13, 2003 at 01:01 UTC

    Take a look at the OODoc module by the author of Mail::Box. Here is a snippet from it's project page:

    The OODoc module is designed to create manual pages independent from the source of the information and the type of output. The documentation may be extracted from the source code with a parser (like the Markov parser, which extends the syntax of POD with logical markup) and the output may be plain POD or HTML.


    cp
    ----
    "Never be afraid to try something new. Remember, amateurs built the ark. Professionals built the Titanic."
[reply]
Re: index of pod files
by PodMaster (Abbot) on May 13, 2003 at 06:43 UTC
    Try Pod::Master, it's all I use (the upcoming official cpan release is gonna be kickin').

    You may also wanna try mpod2html (as in Marek::Pod::HTML).

    Beware of Pod::Tree, for it will overwrite pod2html (what the author does with the utilities is super bizzare -- if one disappears, he recreates it).

    MJD says you can't just make shit up and expect the computer to know what you mean, retardo!
    I run a Win32 PPM repository for perl 5.6x+5.8x. I take requests.
    ** The Third rule of perl club is a statement of fact: pod is sexy.

[reply]
Re: index of pod files
by Abigail-II (Bishop) on May 12, 2003 at 23:41 UTC
    I am not aware of any tools that create indices for POD files. Indices are one of the weak points of the POD model. You probably have to write a tool yourself, using some of the POD:: modules.

    Abigail

[reply]
Re: index of pod files
by thor (Priest) on May 13, 2003 at 04:09 UTC
    I might get branded a heretic (or off-topic) for this, but I really like javadoc. Invoke javadoc on a directory of source, it rips out the documentation and puts it in to a pretty nicely framed HTML page with all of the methods and objects cross-referenced. I imagine that it's even better than novice attempts make it out to be.

    thor

[reply]
Re: index of pod files
by gmpassos (Priest) on May 13, 2003 at 16:12 UTC
    See the POD::Master. But if you want to test your POD easy, take a look at POD-Browser 0.01 released..

    Graciliano M. P.
    "The creativity is the expression of the liberty".

[reply]
Re: index of pod files
by rruiz (Monk) on May 14, 2003 at 01:23 UTC

    Earlier this afternoon I was searching for tutorials on bioperl and found that the documentation page for the project, is generated from sources with the pdoc program. You may want to take a look at it.

    HTH, God bless you
    rruiz

[reply]

Back to Seekers of Perl Wisdom