ppm and autogeneration of documentation

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

Replies are listed 'Best First'.
Re: ppm and autogeneration of documentation by $code or die (Deacon) on Oct 09, 2001 at 17:02 UTC
There are two such scripts on the monastary that do this. They both scan @INC ~~your %perl%\html folder~~ for .pm\.pod files that don't have html docs yet. So you'd run this after installing a module from the CPAN. I can only find one at the moment. I'll add the other one when I find it. Find and convert all pod to html Update: The other one is Update HTML Doc by rudif. I prefer this one because it has more options, the most important IMO is the option of forcing an update of all html docs - so if you upgrade a module you can get the latest docs converted to html. Update 2: Just noticed - I meant @INC not %perl%\html! Simon Flack ($code or die) `$,=reverse'"ro_';s,$,\$,;s,$,lc ref sub{},e;$, =~y'_"' ';eval"die";print $_,lc substr$@,0,3;`	[reply]
Re: Re: ppm and autogeneration of documentation by tachyon (Chancellor) on Oct 09, 2001 at 19:34 UTC
Thanks $code_or_die. The rudif link was the one I was after. In the meantime I got an attack of RTFS and whipped up the script below anyway. It is very simple to use. Just install it in you path somewhere like `C:\Perl\bin` for instance and call it something like `intstalldoc.bat` Then after you have done the usual you just call it: C:\>perl makefile.PL C:\>nmake C:\>nmake test C:\>nmake install C:\>installdoc It reads the Makefile for the TO_INST_PM list of just installed modules, does the pod2html bit and rewrites the AS documentation TOC. If also forces overwrites of existing HTML documentation. The stuff at the start is the standard batch file wrapper so you can just call the script with a one word name. Update Fixed bug when TO_INST_PM contains file with .pm.html extension. @rem = '---Perl--- @echo off if "%OS%" == "Windows_NT" goto WinNT perl -x -S "%0" %1 %2 %3 %4 %5 %6 %7 %8 %9 goto endofperl :WinNT perl -x -S "%0" %* if NOT "%COMSPEC%" == "%SystemRoot%\system32\cmd.exe" goto endofperl if %errorlevel% == 9009 echo You do not have Perl in your PATH. if errorlevel 1 goto script_failed_so_exit_with_non_zero_val 2>nul goto endofperl @rem '; #!/usr/bin/perl -w use strict; use ActivePerl::DocTools; use Pod::Html; my $makefile; my $htmlbase = $ActivePerl::DocTools::TOC::dirbase; $htmlbase =~ tr\|\\\|/\|; my ($dirbase) = $htmlbase =~ m\|(.)/html\|; open MF, './Makefile' or die "Can't open Makefile: $!\n"; { local $/; $makefile = <MF>; } close MF; my ($files) = $makefile =~ m/TO_INST_PM = (.?)PM_TO_BLIB/s; $files =~ tr/\n\\//d; for my $file ( split ' ', $files ) { my ($name) = $file =~ m/(.*)\.pm$/; next unless $name; print "Writing $htmlbase/$name.html\n"; (my $winpath = "$htmlbase/site/$name.html" ) =~ tr\|/\|\\\|; `attrib -r -a $winpath` if -e "$htmlbase/site/$name.html"; pod2html( "--infile=$dirbase/site/$file", "--header", "--htmlroot=$htmlbase", "--podroot=$dirbase", "--podpath=site/lib:lib", "--css=$htmlbase/Active.css", "--outfile=$htmlbase/site/$name.html", "--quiet" ); } ActivePerl::DocTools::WriteTOC(); __END__ :endofperl [download] cheers tachyon s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print	[reply] [d/l]
Re: ppm and autogeneration of documentation by ajt (Prior) on Oct 09, 2001 at 16:14 UTC
If I recall correctly you have to do the POD to HTML conversion yourself, and then tar.gz it into the PPM yourself - not all modules do this for you. So if you grab a module from CPAN, you have to to pod2html yourself, then edit the perltoc.html file by hand. Have a look at ActiveState's PPM FAQ. It's easy to do but tedious.....	[reply]
Re: Re: ppm and autogeneration of documentation by tachyon (Chancellor) on Oct 09, 2001 at 16:20 UTC
Yeah, I know how to use pod2html and edit HTML but I am sure someone wrote a script that does it using the active state modules just as occurs when you run ppm. I remember thinking I should grab that at the time but....cheers tachyon s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print	[reply]
Re: ppm and autogeneration of documentation by jmcnamara (Monsignor) on Oct 10, 2001 at 14:28 UTC
I often build a `ppm` file of downloaded modules so that I can install the docs in the right place and so that the local `ppm` log is kept up to date. However, if you only wish to install the docs then your solution above is probably better. I use the scipt that is included in Jan (Jenda) Krynicky's How2 - create a PPM distribution. I also use this for modules that I upload to CPAN so that they can be installed via `ppm`. -- John.	[reply]
Re: Re: ppm and autogeneration of documentation by tachyon (Chancellor) on Oct 10, 2001 at 14:52 UTC
Thanks John! That's an interesting link. It seems farily easy to make a ppm - I'll have to give it a try. cheers tachyon s&&rsenoyhcatreve&&&s&n.+t&"$'$`$\"$\&"&ee&&y&srve&&d&&print	[reply]

Update