Need advise on documentation support tools in Perl

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

I have a fair sized application to provide documentation and help files for.

The apps has a feature that makes every label on any form have "hover title" info and help text when you click on it. Given that I have 15 pages with 1 to 5 tabs and 4 to 40 labels I have a large task of keeping track of each of the pieces of help text.

My intent is to produce several target files from the one source file eg. Reference manuel and input file to the help system. I tried out POD on its own and I am running into problem with the number of levels of =head is limited to 4. The alternative is to use the =over =item =back features. I found was typing a lot of repeated text to structure the document and it was taking a long time to do.

I started to think about using text::autoformat to help produce pod text from an indented file. I have no experience with this module and I don't know it is even possible.

Now I am not sure what to do. While typing this question I wondered if there are any data dictionary programs that could keep the tree structure organized and allow anyone to do the input. I could write the programs to do the output.

Has anyone delt with this before.

Disclaimer I like from another Perlmonk.

Comment on Need advise on documentation support tools in Perl

Replies are listed 'Best First'.

Re: Need advise on documentation support tools in Perl
by tall_man (Parson) on Feb 06, 2003 at 20:21 UTC

References: Pod::SDF and Doxygen

[reply]

Re: Need advise on documentation support tools in Perl
by PodMaster (Abbot) on Feb 07, 2003 at 05:59 UTC

Don't rule out pod just yet -- just because officially only head1..4 is supported, don't mean you can't make it head1..n -- grab one of the following, and work some magic ;D Pod::POM, Pod::Tree (watchout for pod2html), Pod::Parser.

XML + templating system is something to think about.

You might also wanna exploit Exuberant CTags (http://ctags.sf.net) and look into DocBook (http://docbook.org)

MJD says you can't just make shit up and expect the computer to know what you mean, retardo!
** The Third rule of perl club is a statement of fact: pod is sexy.

[reply]

Re: Re: Need advise on documentation support tools in Perl

by admiraln (Acolyte) on Feb 10, 2003 at 16:17 UTC

I am using perl to automate some steps in the process so POD came up as a file format to store information that may have to be transformed to other formats.

Disclaimer

[reply]

Re: Need advise on documentation support tools in Perl
by bronto (Priest) on Feb 06, 2003 at 19:50 UTC

It seems that you need XML, fellow :-). Have you any experience on that?

You could define a small format that fits your needs, or use a subset of XHTML (for example) and then have it transformed to POD, LaTeX and/or any useful format that comes into your mind: there are a bunch of ready-made modules on CPAN to do that.

Ciao!
--bronto

The very nature of Perl to be like natural language--inconsistant and full of dwim and special cases--makes it impossible to know it all without simply memorizing the documentation (which is not complete or totally correct anyway).
--John M. Dlugosz

[reply]

Re: Need advise on documentation support tools in Perl
by perrin (Chancellor) on Feb 06, 2003 at 20:31 UTC

Like the previous poster I suggest XML for keeping the structured data and XML::Simple + Template Toolkit (or Text::Template if you prefer) for turning that into whatever you need.

[reply]


Pathologically Eclectic Rubbish Lister
	PerlMonks