home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / tsw / TSW_3.4.0.exe / Apache2 / perl / mpod2html.bat < prev    next >
Encoding:
DOS Batch File  |  2003-11-26  |  11.6 KB  |  437 lines
  1. @rem = '--*-Perl-*--
  2. @echo off
  3. if "%OS%" == "Windows_NT" goto WinNT
  4. perl -x -S "%0" %1 %2 %3 %4 %5 %6 %7 %8 %9
  5. goto endofperl
  6. :WinNT
  7. perl -x -S %0 %*
  8. if NOT "%COMSPEC%" == "%SystemRoot%\system32\cmd.exe" goto endofperl
  9. if %errorlevel% == 9009 echo You do not have Perl in your PATH.
  10. if errorlevel 1 goto script_failed_so_exit_with_non_zero_val 2>nul
  11. goto endofperl
  12. @rem ';
  13. #!perl
  14. #line 15
  15.     eval 'exec D:\Perl\bin\perl.exe -S $0 ${1+"$@"}'
  16.     if $running_under_some_shell;
  17. #!perl -w
  18.  
  19. use strict;
  20. use vars qw($VERSION $TEST_MODE);
  21. $VERSION = 0.2;
  22.  
  23. use Getopt::Long;
  24.  
  25. use Pod::Find qw(pod_find simplify_name);
  26.  
  27. my %opt = ( banner => 1 );
  28.  
  29. # compatibility hack for previous version(s) of pod2html
  30. my %oldopt;
  31.  
  32. die unless(GetOptions(\%opt, qw(
  33.   banner!
  34.   converter=s
  35.   suffix=s
  36.   filesuffix=s
  37.   dir=s
  38.   libpods=s
  39.   navigation!
  40.   localtoc!
  41.   toc!
  42.   idx!
  43.   tocname=s
  44.   idxname=s
  45.   toctitle=s
  46.   idxtitle=s
  47.   idxopt=s
  48.   ps!
  49.   psdir=s
  50.   psfont=s
  51.   papersize=s
  52.   inc!
  53.   script!
  54.   stylesheet=s
  55.   warnings!
  56.   verbose!
  57.   help|h
  58.   version|V),
  59.     'flush' => \$oldopt{flush},
  60.     'htmlroot=s' => \$oldopt{htmlroot}, # can be ignored
  61.     'index!' => \$oldopt{'index'},
  62.     'infile=s' => \$oldopt{infile},
  63.     'netscape!' => \$oldopt{netscape}, # ignore
  64.     'outfile=s' => \$oldopt{outfile},
  65.     'podpath=s' => \$oldopt{podpath}, # can be ignored
  66.     'podroot=s' => \$oldopt{podroot},
  67.     'recurse!' => \$oldopt{recurse}, # ignored now
  68.     'title=s' => \$oldopt{title}
  69. ));
  70.  
  71. my %addopts = ();
  72.  
  73. if($oldopt{infile}) {
  74.   @ARGV = ( $oldopt{infile} );
  75. }
  76.  
  77. if($oldopt{outfile}) {
  78.   $addopts{-outfile} = $oldopt{outfile};
  79. }
  80.  
  81. if($oldopt{podroot}) {
  82.   push(@ARGV, $oldopt{podroot});
  83. }
  84.  
  85. # process libpods
  86. if($opt{libpods}) {
  87.   # replace single : with , (old style)
  88.   $opt{libpods} =~ s/(?<!:):(?!:)/,/g;
  89. }
  90.  
  91. if(defined $oldopt{'index'}) {
  92.   $opt{localtoc} = $oldopt{'index'};
  93. }
  94.  
  95. if(defined $oldopt{title}) {
  96.   $addopts{-title} = $oldopt{title};
  97. }
  98.  
  99. my $converter = $opt{converter} || 'Marek::Pod::HTML';
  100. eval "use $converter qw(pod2html);";
  101. die "Fatal: Cannot load convertor module '$converter':\n$@\n"
  102.     if($@);
  103.  
  104. if($opt{help}) {
  105.   use Config;
  106.   exec "$Config{scriptdir}/perldoc -F $0";
  107. }
  108. elsif($opt{version}) {
  109.     print "$0 Version $VERSION\n";
  110. }
  111. else {
  112.  
  113.     my %pods = ();
  114.     my @dirs = ();
  115.  
  116.     foreach(@ARGV) {
  117.         if(-d) {
  118.             push(@dirs,$_);
  119.         }
  120.         elsif(/[*?]/) {
  121.             foreach (glob($_)) {
  122.                 if(-d) {
  123.                     push(@dirs,$_);
  124.                 }
  125.                 else {
  126.                     my $name = simplify_name($_);
  127.                     $pods{$_} = $name;
  128.                 }
  129.             }
  130.         }
  131.         else {
  132.            my $name = simplify_name($_);
  133.            $pods{$_} = $name;
  134.        }
  135.     }
  136.     my %search;
  137.  
  138.     if(@dirs || $opt{inc} || $opt{script}) {
  139.         warn "+++ Searching for POD documents\n";
  140.         %search = pod_find({
  141.             -inc => $opt{inc},
  142.             -script => $opt{script},
  143.             -verbose => $opt{verbose}
  144.           }, @dirs)
  145.     }
  146.  
  147.     map { $pods{$_} = $search{$_} } keys %search;
  148.  
  149.     # run as a filter
  150.     # we have to save it temporarily because we need two passes
  151.     my $tmp;
  152.     unless(%pods) {
  153.         my $self = $0;
  154.         $self =~ s:^.*/::;
  155.         $tmp = "/tmp/$self.$$";
  156.         open(TEMP, ">$tmp") || die "Cannot write temp file: $!\n";
  157.         while(<STDIN>) {
  158.             print TEMP;
  159.         }
  160.         close(TEMP);
  161.         $pods{$tmp} = 'stdin';
  162.         $addopts{-filter} = 1;
  163.         $opt{navigation} = 0 unless defined $opt{navigation};
  164.     }
  165.  
  166.     warn "+++ Starting conversion\n" if($opt{verbose});
  167.  
  168.     pod2html( {
  169.         -banner => $opt{banner},
  170.         -converter => $converter,
  171.         -suffix => $opt{suffix},
  172.         -filesuffix => $opt{filesuffix},
  173.         -dir => $opt{dir},
  174.         -libpods => $opt{libpods},
  175.         -navigation => $opt{navigation},
  176.         -localtoc => $opt{localtoc},
  177.         -toc => $opt{toc},
  178.         -idx => $opt{idx},
  179.         -tocname => $opt{tocname},
  180.         -idxname => $opt{idxname},
  181.         -toctitle => $opt{toctitle},
  182.         -idxtitle => $opt{idxtitle},
  183.         -ps => $opt{ps},
  184.         -psdir => $opt{psdir},
  185.         -psfont => $opt{psfont},
  186.         -papersize => $opt{papersize},
  187.         -warnings => $opt{warnings},
  188.         -verbose => $opt{verbose},
  189.         -stylesheet => $opt{stylesheet},
  190.         -idxopt => $opt{idxopt},
  191.         %addopts
  192.     }, { %pods });
  193.  
  194.     unlink $tmp if($tmp);
  195. }
  196.  
  197. exit 0 unless($TEST_MODE);
  198. 1; # this is for the module test
  199.  
  200. __END__
  201.  
  202. =head1 NAME
  203.  
  204. pod2html - convert Perl POD documentation to HTML
  205.  
  206. =head1 SYNOPSIS
  207.  
  208. B<pod2html> S<[ B<-converter> I<module> ]>
  209. S<[ B<-suffix> I<suffix> ]> S<[ B<-filesuffix> I<suffix> ]>
  210. S<[ B<-dir> I<path> ]> S<[ B<-libpods> I<pod1,pod2,...> ]>
  211. S<[ B<->(B<no>)B<localtoc> ]> 
  212. S<[ B<->(B<no>)B<navigation> ]> 
  213. S<[ B<->(B<no>)B<toc> ]> S<[ B<-tocname> I<filename> ]>
  214. S<[ B<-toctitle> I<title> ]>
  215. S<[ B<->(B<no>)B<idx> ]> S<[ B<-idxopt> I<options> ]>
  216. S<[ B<-idxname> I<filename> ]>
  217. S<[ B<-idxtitle> I<title> ]>
  218. S<[ B<->(B<no>)B<ps> ]> 
  219. S<[ B<-psdir> I<path> ]> S<[ B<-psfont> I<font> ]>
  220. S<[ B<-papersize> I<format> ]>
  221. S<[ B<->(B<no>)B<inc> ]> 
  222. S<[ B<->(B<no>)B<script> ]> 
  223. S<[ B<->(B<no>)B<warnings> ]> 
  224. S<[ B<->(B<no>)B<verbose> ]> 
  225. S<[ B<->(B<no>)B<banner> ]> 
  226. S<[ B<-stylesheet> I<link> ]>
  227. S<[ I<dir1> , I<dir2> , ... ]>
  228. S<[ I<pod1> , I<pod2> , ... ]>
  229.  
  230. =head1 DESCRIPTION
  231.  
  232. B<mpod2html> converts Perl POD documentation to HTML. This was
  233. originally meant as a replacement for the existing core
  234. C<pod2html>, but has turned out to be a heavy-weight, fancy
  235. HTML converter that needs quite a lot of additional modules.
  236. There are a lot of other Pod to HTML converters out there that
  237. may suit you needs better.
  238.  
  239. See L<SEE ALSO> below for sources of more details.
  240.  
  241. An important note: B<mpod2html> will cross-link I<only>
  242. those documents that are processed in one conversion
  243. session. The benefit is that you will get I<only>
  244. working hyperlinks, no "dead ends". The downside is that
  245. you cannot simply convert one additional Pod and everything
  246. will be nicely crosslinked. Future versions of this module
  247. (or a complete rewrite) may support a caching mechanism 
  248. for the hyperlink destination, such that additional Pods
  249. converted to HTML will have working hyperlinks to the
  250. existing, already converted Pods; but updating all
  251. existing HTML files for links to the newly converted Pod
  252. is rather cumbersome.
  253.  
  254. =head1 OPTIONS
  255.  
  256. =over 4
  257.  
  258. =item B<-converter> I<module>
  259.  
  260. The converter class to use, defaults to C<Marek::Pod::HTML>. This hook allows
  261. for simple customization, see also L<Marek::Pod::HTML/"Customizing">.
  262.  
  263. =item B<-suffix> I<string>
  264.  
  265. Use this string for links to other converted Pod documents. The default
  266. is C<.html> and also sets the filename suffix unless B<-filesuffix> has
  267. been specified. The dot must be included!
  268.  
  269. =item B<-filesuffix> I<string>
  270.  
  271. Use this string as a suffix for the output HTML files. This does not
  272. change the suffix used in the hyperlinks to different documents. This
  273. feature is meant to be used if some (Makefile based) postprocessing
  274. of the generated files has to be performed, but without having to
  275. adapt the links.
  276.  
  277. =item B<-dir> I<path>
  278.  
  279. Write the generated HTML files (can be a directory hierarchy) to this
  280. path. The default is the current working directory.
  281.  
  282. =item B<-libpods> I<name1,name2,...>
  283.  
  284. This option activates a highly magical feature: The C<=item> nodes of
  285. the specified Pod documents (given by Pod name, e.g. C<Pod::Parser>)
  286. serve as destinations for highlighted text in all converted Pod
  287. documents. Typical usage: When converting your Perl installation's
  288. documentation, you may want to say
  289.  
  290.   pod2html -libpods perlfunc,perlvar,perlrun -script -inc
  291.  
  292. then you will get a hyperlink to L<perlvar|perlvar> in the text
  293. C<IE<lt>$|E<gt>>.
  294.  
  295. =item B<-localtoc> | B<-nolocaltoc>
  296.  
  297. This is by default true, so that at the top of the page a local
  298. table of contents with all the C<=head>I<n> lines is generated.
  299.  
  300. =item B<-navigation> | B<-nonavigation>
  301.  
  302. When using the default customization, this flag enables or disables
  303. the navigation in the header of each Pod document (next/previous doc,
  304. table of contents, index).
  305.  
  306. =item B<-toc> | B<-notoc>
  307.  
  308. If true, a table of contents is built from the processed Pod documents.
  309.  
  310. =item B<-tocname> I<name>
  311.  
  312. Use I<name> as the filename of the table of contents. Default is
  313. F<podtoc>. The general file suffix is added to this name.
  314.  
  315. =item B<-toctitle> I<string>
  316.  
  317. The string that is used as the heading of the table of contents.
  318. Default is `Table of Contents'.
  319.  
  320. =item B<-idx> | B<-noidx>
  321.  
  322. If true, an index is built from all processed Pod documents.
  323.  
  324. =item B<-idxopt> I<options>
  325.  
  326. Options for index building. Default is "item,x", which means that
  327. item strings as well as text marked up with C<XE<lt>...E<gt>> 
  328. generate entries in the index.
  329.  
  330. =item B<-idxname> I<name>
  331.  
  332. Use I<name> as the filename of the index. Default is
  333. F<podindex>. The general file suffix is added to this name.
  334.  
  335. =item B<-idxtitle> I<string>
  336.  
  337. The string that is used as the heading of the table of contents.
  338. Default is `Index'.
  339.  
  340. =item B<-ps> | B<-nops>
  341.  
  342. In addition to HTML, generate also Postscript output. The suffix is
  343. F<.ps>. Default is no.
  344.  
  345. =item B<-psdir>
  346.  
  347. The root directory where to write Postscript files. Defaults to the
  348. same as B<-dir>.
  349.  
  350. =item B<-psfont> I<fontname>
  351.  
  352. Generate Postscript files using the font I<fontname>. Default is
  353. `Helvetica'.
  354.  
  355. =item B<-papersize> I<size>
  356.  
  357. Generate Postscript files using the paper size I<size>. Default is
  358. `A4'.
  359.  
  360. =item B<-inc> | B<-noinc>
  361.  
  362. In addition to the files specified on the command line, use
  363. L<Pod::Find> to traverse C<@INC> for all Pod documents. For a
  364. decent Perl installation this will collect a I<huge> number
  365. of files.
  366.  
  367. =item B<-script> | B<-noscript>
  368.  
  369. Similar to B<-inc>, this looks in the Perl installation
  370. executables directory for scripts containing Pod to be
  371. converted. Using this, you will e.g. catch C<perldoc>.
  372.  
  373. =item B<-warnings> | B<-nowarnings>
  374.  
  375. When processing the first pass, print warnings. See L<Pod::Checker>
  376. for more information on warnings. Note: This can produce a lot of
  377. output if the Pod source does not correspond to strict guidelines.
  378.  
  379. =item B<-verbose> | B<-noverbose>
  380.  
  381. Print more status information along the conversion process.
  382.  
  383. =item B<-banner> | B<-nobanner>
  384.  
  385. Generate a banner at the bottom of all converted files (or not).
  386. Default is true.
  387.  
  388. =item B<-stylesheet> I<link>
  389.  
  390. The (optional) link to a style sheet, which is included in the resulting HTML
  391. as
  392.  
  393.   <LINK TYPE="text/css" REL="stylesheet" HREF=$link>
  394.  
  395. =back
  396.  
  397. =head1 ARGUMENTS
  398.  
  399. =over 4
  400.  
  401. =item I<none>
  402.  
  403. If no arguments are specified (and neither B<-inc> nor
  404. B<-script>), then B<mpod2html> acts as a filter, reading
  405. STDIN and writing to STDOUT.
  406.  
  407. =item I<dir1> , I<dir2> , ...
  408.  
  409. Directories specified on the command line will be processed
  410. recursively. This means especially that if there is e.g. 
  411. F<Pod/Checker.pm> in the specified directory, it will be
  412. recognized as C<Pod::Checker> (rather than C<Checker>).
  413.  
  414. =item I<pod1> , I<pod2> , ...
  415.  
  416. A list of files. Note that if you specify F<Mail/Alias.pm>, then
  417. this is I<not> recognized as C<Mail::Alias>, with the consequence
  418. that links in other documents pointing to C<Mail::Alias> will
  419. not be resolved.
  420.  
  421. =back
  422.  
  423. =head1 AUTHOR
  424.  
  425. Marek Rouchal E<lt>marekr@cpan.orgE<gt>
  426.  
  427. =head1 SEE ALSO
  428.  
  429. L<Marek::Pod::HTML>,
  430. L<HTML::Element>, L<Pod::Parser>, L<Pod::Checker>, L<HTML::Entities>
  431.  
  432. =cut
  433.  
  434.  
  435. __END__
  436. :endofperl
  437.