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

[Jonathan S. <gel...@ge...>]

On Tue, 26 Mar 2002, Dave Cross wrote:

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

I think the only advantage to it is that if the program file gets
separated from its README then the documentation is still there, but yeah
I think basically you are right.

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

Yeah, I'd concur with that.  I thought that I had started on a DTD for
that very purpose but I'm buggered if I can find any sign of it.  I
wouldn't think that it need be very complicated - not much more than:

<!ELEMENT nms_readme (summary,files,configuration, installation) >
   <!ATTLIST nms_readme prog_file CDATA #REQUIRED
                        full_name CDATA #REQUIRED>

   <!ELEMENT paragraph (#PCDATA)>

   <!ELEMENT summary (paragraph*)>

   <!ELEMENT files (file*)>

      <!ELEMENT file (filename, filedesc)>
         <!ELEMENT filename (#PCDATA)>
         <!ELEMENT filedesc (#PCDATA)>

   <!ELEMENT configuration (introduction, variables*)>

      <!ELEMENT introduction (paragraph*)>

      <!ELEMENT variables (variable*)>

         <!ELEMENT variable (var_name, description)>

            <!ELEMENT var_name (#PCDATA)>

            <!ELEMENT description (paragraph*)>

   <!ELEMENT installation (paragraph*)>


The rest is just boilerplate that can either be defined as entities in the
DTD or hard coded in the XSLT.

You could even generate the MANIFEST from it and probably drive the
creation of the distribution files.

It would be a piece of piss to knock together a little program.
Its a shame that XML::XSLT doesn't do the text part very well :)

Unless someone else is dead keen on getting on with this I will do the
conversion at the weekend.

Other things that will be required for this effort are:

   * XSLT stylesheet to generate text and HTML versions of the README

   * Build program for distribution to generate README and MANIFEST

   * Loads of other stuff I haven't thought about yet

While I think about it it might also be worth thinking about going down
this route with the Changelogs as well - I have made a small amendment to
cvs2cl that works nicely with the local style of putting '*' bullet points
in the cvs log - this then generates XML that is further transformed to
text for the distribution and HTML for the web site.


/J\
-- 
Jonathan Stowe                      |
<http://www.gellyfish.com>          |      This space for rent
                                    |