[Omaha.pm] FW: Pod::Tree - .pm files w/ no POD?

["Jay Hannah" <jhannah@omnihotels.com>]

Steven's response...

j


-----Original Message-----
From: Steven W McDougall [mailto:swmcd@theworld.com]
Sent: Thursday, July 22, 2004 7:29 AM
To: jhannah@omnihotels.com
Subject: Re: Pod::Tree - .pm files w/ no POD?


> I just discovered pods2html. Very cool! 

Thank you :)


> We have a lot of .pm files that do have POD, and even more .pm files
  that don't have POD. Unfortunately, the no POD .pm files do create
  an (empty) .html file, and are added to the index.

People have complained about this before, and I've taken the position
that pods2html correctly translates an empty POD file to an empty HTML
file, and that I didn't want to special-case the code to suppress the
HTML files. BUT...having empty HTML files show up in the index is
obviously the Wrong Thing. 


> I noticed you're also the author of Pod::Tree, so I just thought I'd
  send this to you, wondering if you'd want a patch to
  Pod::Tree::has_pod() which would (optionally?) return false if the
  .pm file didn't actually have any POD in it...? Then I guess an
  option would have to be added to pods2html as well to pass that in?

Some new options to the modues and executables to suppress empty HTML
files is probably the simplest fix. I'll try to get a release out
sometime in August.


> (First I played with Pod::Tree::PerlPod, which seems to create the
  same phenomenon. I'm unclear about the differences between
  Pod::Tree::PerlPod and pods2html...)

Modules
Pod::Tree	 parses a POD into a syntax tree
Pod::Tree::HTML  walks a syntax tree and generates HTML
Pod::Tree::Perl* converts the PODs in the Perl source distribution to HTML

Executables
pod2html	 calls Pod::Tree and Pod::Tree:HTML to 
		 convert a single POD file to an HTML file

pods2html	 calls Pod::Tree and Pod::Tree:HTML to 
		 convert all the POD files in a directory tree to HTML
		 files in a parallel directory tree

perl2html	 calls Pod::Tree::Perl* to convert all the PODs in 
		 - the Perl source distribution
		 - installed Perl modules
		 - installed Perl executables
		 to HTML files. An example of the resulting HTML tree 
		 can be seen at http://www.perldoc.com/



Let me know if you need more help with this.



- SWM