introspection, or running pod2html on itself

punkish has asked for the wisdom of the Perl Monks concerning the following question:

my script

# lots of code, intermingled with lots of pod
...

# Generate html documentation if --makedoc switch is used
my $makedoc  = '';
GetOptions('makedoc' => \$makedoc);

if ($makedoc) {
  makeDoc();
}

# Then, further down
sub makeDoc {
  my $in = "$full_path/myscript.pl";
  my $out = "$full_path/docs/myscript.html";

# Note: updated the above two lines with double-quotes
  
  qx(pod2html --title='$title' --infile=$in --outfile=$out);
}
[download]

pod2html croaks with the message that it couldn't file the in file.

Finally, I have to pack the above script as an '.exe' using pp. Eventually, the user should be able to generate the documentation herself by running something like

myscript.exe --makedoc
[download]

Any advice welcome.

Update: changed single-quotes to double-quotes in the sub makeDoc above. The single-quotes were inadvertant... the real code in fact has the full path name typed in verbatim.

--

when small people start casting long shadows, it is time to go to bed

Comment on introspection, or running pod2html on itself Select or Download Code

Replies are listed 'Best First'.
Re: introspection, or running pod2html on itself by jmcnamara (Monsignor) on Sep 15, 2005 at 15:11 UTC
You could use the core Pod::Html module directly just as pod2html does. Something like this: `#!/usr/bin/perl -w use strict; use Pod::Html; # Set the Pod::Html options such as --outfile my @html_options = ('--title=My Test'); # Some getopt code here for program options. # ... pod2html __FILE__, @html_options; __END__ =head1 TEST Some pod here. =cut` [download] See also Pod::Usage for a text, rather than Html, way of displaying the embedded documentation. -- John.	[reply] [d/l]
Re^2: introspection, or running pod2html on itself by punkish (Priest) on Sep 15, 2005 at 16:15 UTC
> You could use the core Pod::Html module directly Works beautifully. Many thanks. -- when small people start casting long shadows, it is time to go to bed	[reply]
Re^3: introspection, or running pod2html on itself by punkish (Priest) on Sep 15, 2005 at 20:46 UTC
I spoke too soon. While Pod::Html does work very well, everything fails against a packed .exe created with pp. Seems like the package stuffs the script inside a folder within the .exe. So, if my script is myscript.pl, and I do the following `pp -o myscript.exe myscript.pl` [download] myscript.pl gets stuffed as script/myscript.pl within the confines of myscript.exe. Hence, pod2html is unable to create anything against myscript.exe (because the pod is hidden inside the script). That is very disappointing. I could take other monks' advice and use the __DATA__ block to store my html doc and then spit it out as needed, however, I have already got everything mapped out and typed up in pod. What a chore to extract it and redo as html. unless... any suggestions (asks hopefully). By the way, how do I find out the full path of the current script? __FILE__ or $0 give only the filename (actually, __FILE__ against the above exe gives script/myscript.pl) -- when small people start casting long shadows, it is time to go to bed	[reply] [d/l]
Re^4: introspection, or running pod2html on itself by Anonymous Monk on Oct 23, 2009 at 12:15 UTC
Re: introspection, or running pod2html on itself by halley (Prior) on Sep 15, 2005 at 14:37 UTC
Yikes. Your plan will require that end-users have 'pod2html' available to them, and that you can feed pod2html the original perl scripts which made your pp executable. And avoid hard-coded paths! Instead, if you really want to internally pack your documentation so you only need to ship one executable file, I would suggest you run pod2html yourself, and stuff that into a __DATA__ block in one of the compiled script files. Then your --makedoc command can regurgitate that stuff into .html files directly. I haven't used pp much; maybe it can even include various non-Perl files which are required by the executable. Then you wouldn't even need a __DATA__ hack to include the html content. -- `[ e d @ h a l l e y . c c ]`	[reply]
Re^2: introspection, or running pod2html on itself by punkish (Priest) on Sep 15, 2005 at 15:11 UTC
Yikes. Your plan will require that end-users have 'pod2html' available to them, and that you can feed pod2html the original perl scripts which made your pp executable. And avoid hard-coded paths! Rats! That is a bloody good point, that I had not thought of. Given that, your suggestion for embedding the html as a __DATA__ block, or even as a scalar (using HEREDOC), and then spitting that out, might be the best for now. However, being able to spit out customized html might be worthwhile in other situations. For example, if I include a --configure option which configures the script for the user, then have --makdoc deliver a customized documentation. In that case, I would still need to figure out how to embed pod2html itself inside the .exe using pp. Any suggestions welcome. -- when small people start casting long shadows, it is time to go to bed	[reply]
Re^3: introspection, or running pod2html on itself by radiantmatrix (Parson) on Sep 15, 2005 at 20:38 UTC
If you use a HEREDOC, you can have variables to interpolate inside it, meaning you can still dump custom documentation. If you take the __DATA__ route, you can use a template system to generate the custom docs. Finally, you could include the module POD::HTML in your packed executable and have a subroutine defined in your script that will `require` it and essentially do what `pod2html` does for you. <-radiant.matrix-> Larry Wall is Yoda: there is no `try{}` (ok, except in Perl6; way to ruin a joke, Larry! ;P) The Code that can be seen is not the true Code "In any sufficiently large group of people, most are idiots" - Kaa's Law	[reply]
Re: introspection, or running pod2html on itself by dave_the_m (Monsignor) on Sep 15, 2005 at 13:57 UTC
`my $in = '$full_path/myscript.pl'; my $out = '$full_path/docs/myscript.html';` [download] You need double-quotes there, not single. Dave.	[reply] [d/l]
Re^2: introspection, or running pod2html on itself by punkish (Priest) on Sep 15, 2005 at 14:10 UTC
The single-quotes were inadvertant... the real code in fact has the full path name typed in verbatim. I have updated the OP to reflect this. -- when small people start casting long shadows, it is time to go to bed	[reply]
Re: introspection, or running pod2html on itself by xdg (Monsignor) on Sep 15, 2005 at 14:51 UTC
Can you post the actual error message as well as the code that populates `$full_path`? And have you tried this directly from perl with Pod::HTML instead of using the command shell with `qx` -xdg Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.	[reply] [d/l] [select]