in reply to Crash Course in POD

Learning about POD
Try perldoc perlpod for the POD man page.

Single point of documentation
Remember that single text documents tend to vanish leaving the new maintainer/developer unaware of all the hassle you went though. I'd write the POD into all the scripts and then copy the useful bits into a separate file. It's more work, but it'll be more useful to the next coder.

Documenting a large project
As to your last question. DON'T TOUCH THE CODE! Yes, documenting is a pain, and boring and I'm sure you can see 1001 ways to make the code a little clearer but if you're not being paid to fix the code and it's in production, don't touch it. It works (presumably), leave it alone.

Just go in, test away, work out what it does, try to guess how it does it, and document what you can understand. It's (probably) okay to put stuff like:

##### Warning: through inspection, it appears that the ##### following code may fail under these circumstances: # A) ..... # B) ..... # C) ..... ##### A possible solution is in the following (untested) ##### code: # ......... # .........
but remember what you're being paid to do. Adding documentation to a program should never alter it's functionality. (Well, unless you're playing with Damian's selfgol).

If you feel that something really ought to be changed, write it down and bring it up with your supervisor after the documentation project has been completed. Don't allow yourself to be pressured into making functional changes at the same time as you're making formatting/documentation changes. Something will go wrong and your documentation will get blamed.

Oh, and use CVS. Or some other revision control system. And check your changes in regularly, although probably on a code branch and not directly into the main tree.

Lastly:
Good luck!

Hope it helps.

jarich

Replies are listed 'Best First'.
Re: Re: Crash Course in POD
by jens (Pilgrim) on Sep 25, 2002 at 02:40 UTC
    Single point of documentation
    <snip>... I'd write the POD into all the scripts and then copy the useful bits into a separate file. It's more work, but it'll be more useful to the next coder.


    Having a single point of documentation is one of the most important reasons I want to use POD--that way a change to the commented source is immediately reflected in the Programmer's Manual.

    But when you say to "copy the useful bits into a separate file" this doesn't solve the problem.

    Is there a way, in POD, to accumulate POD comments in multiple files into one larger document? This way there would truly be a single point of documentation.

    --
    Microsoft delendum est.
      Is there a way, in POD, to accumulate POD comments in multiple files into one larger document? This way there would truly be a single point of documentation.

      There is no way in POD, but there are many ways in Perl (at least, there is more than one way...) Go to http://www.cpan.org/modules/01modules.index.html and you will find more than 30 modules dealing with POD. In your case, maybe Pod-Simple or Pod-Parser is what you need.

      With either module, extract the POD from each file and copy it to the result file. That's simple.