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

[Dave C. <da...@da...>]

On Tue, Mar 26, 2002 at 09:51:38PM +0000, Nick Cleaton (ni...@cl...) wrote:
> 
> This is going to be a problem so long as we have the docs
> duplicated in the README and in FormMail.pl.
> 
> It's nice having them in POD, and having them in FormMail.pl
> allows the use of a CVS revision tag, also nice.
> 
> How about deleting the README from CVS and generating
> a README at release time with something like:
> 
>   pod2text -qnone -w72 FormMail.pl >README
> 
> The pod2text that comes with perl 5.6.1 does a pretty
> good job IMO.
> 
> We could even have readme.html as a bonus :)
> 
> Dave, would that be easy ?

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?

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.

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.
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.

I am, of course, open to other opinions on any of this.

Dave...

-- 

  .sig missing...