Re: [Nms-cgi-devel] Re: [Nms-cgi-commits] CVS Commit

[Nick C. <ni...@cl...>]

On Tue, Mar 26, 2002 at 10:19:50PM +0000, Dave Cross wrote:
>
> I was thinking about similar things earlier today. I was wondering what the
> advantages are of having the POD inside the Perl script. It seems to me that
> this is only an advantage with modules as perldoc will search @INC for POD
> to display. That doesn't work for scripts does it?

The only thing I would say against that is that the CVS $Revision$
thing only works for docs that are right there in FormMail.pl.

> I also tend to the opinion that raw POD is potentially too confusing for
> our target audience and we shouldn't be showing it to them.

Well, it is at the end :)

> My plan (and I was planning on starting on this real soon now) was to convert
> all of the READMEs to XML and to generate text and HTML versions with XSLT.

And POD ?

> This seemed, to me, to have the advantage that the individual files would only
> contain the stuff that differs from script to script and the common stuff
> (like copyright and support information) would be stored externally so 
> there's less chance of it getting out of step.

Sounds good, so long as you do sufficient XSLT magic at release
time to make sure all the revision information is correct in all
files.

Especially good if this means we can cut down on code duplicated
between scripts.

And of course the XSLT scripts to do all that stuff will need
to be in the CVS tree and runnable on everyone's platforms so
that we can all test our changes before checking them in. 

Another point: at the moment people can just grab the latest
script straight of of CVS via the web to try out prerelease
things.  I wouldn't like to see that get a lot harder, so some
sort of automatic pre-release thing that tracks CVS exactly
is probably in order.

--
Nick