Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses
 
PerlMonks  

Need advise on documentation support tools in Perl

by admiraln (Acolyte)
on Feb 06, 2003 at 19:14 UTC ( #233235=perlquestion: print w/ replies, xml ) Need Help??
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
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
Re: Need advise on documentation support tools in Perl
by tall_man (Parson) on Feb 06, 2003 at 20:21 UTC
    Tools I have used to automate the production of documentation in multiple formats include SDF and Doxygen. (The latter is more suited to large C++ projects but it's possible to adapt it for perl).

    References: Pod::SDF and Doxygen

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.
Re: Need advise on documentation support tools in Perl
by PodMaster (Abbot) on Feb 07, 2003 at 05:59 UTC
    What kind of application is this (where's the POD, inline or what)?

    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.

      The POD is nowhere yet. The system is written in PHP and I am responsible for preparing it for release. This will include logging bugs as I discover them but primarily to document the system as it stands in a way that will let the help files be updatable when the code will evolve.

      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

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://233235]
Approved by Enlil
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others drinking their drinks and smoking their pipes about the Monastery: (9)
As of 2014-10-01 16:19 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    What is your favourite meta-syntactic variable name?














    Results (29 votes), past polls