Pod::Webserver -- minimal web server to serve local Perl documentation

       Original author: Sean M. Burke "sburke@cpan.org"

       Maintained by: Allison Randal "allison@perl.org"

perl v5.8.8                                        2006-12-20                                       Webserver(3)

       Copyright (c) 2004-2006 Sean M. Burke.  All rights reserved.

       This library is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.

       This  program  is  distributed in the hope that it will be useful, but without any warranty; without even
       the implied warranty of merchantability or fitness for a particular purpose.

       This  module  can  be  run  as  an  application  that  works  as a minimal web server to serve local Perl
       documentation.  It's like perldoc except it works through your browser.

       Run podwebserver-h for a list of runtime options.

       Pod::Webserver -- minimal web server to serve local Perl documentation

       Pod::Webserver is not what you'd call a gaping security hole -- after all, all it does and could possibly
       do is serve HTML versions of anything you could get by typing "perldoc  SomeModuleName".   Pod::Webserver
       won't serve files at arbitrary paths or anything.

       But  do  consider  whether  you're  revealing  anything by basically showing off what versions of modules
       you've got installed; and also consider whether you could be revealing any proprietary or in-house module
       documentation.

       And also consider that this exposes the documentation of modules (i.e., any Perl files that at  all  look
       like  modules)  in  your  @INC  dirs  --  and  your  @INC probably contains "."!  If your current working
       directory could contain modules whosePod you don't want anyone to see, then you could do two things: The
       cheap and easy way is to just chdir to an uninteresting directory:

         mkdir ~/.empty; cd ~/.empty; podwebserver

       The more careful approach is to run podwebserver under perl in -T (taint) mode (as explained in perlsec),
       and to explicitly specify what extra directories you want in @INC, like so:

         perl -T -Isomepath -Imaybesomeotherpath -S podwebserver

       You can also use the -I trick (that's a capital "igh", not a lowercase "ell") to add dirs to @INC even if
       you're not using -T.  For example:

         perl -I/that/thar/Module-Stuff-0.12/lib -S podwebserver

       An alternate approach is to use your shell's environment-setting commands to alter  PERL5LIB  or  PERLLIB
       before starting podwebserver.

       These -T and -I switches are explained in perlrun. But I'll note in passing that you'll likely need to do
       this to get your PERLLIB environment variable to be in @INC...

         perl -T -I$PERLLIB -S podwebserver

       (Or replacing that with PERL5LIB, if that's what you use.)

       ONINDEXING'.'IN@INC

       Pod::Webserver   uses   the   module   Pod::Simple::Search   to   build   the   index  page  you  see  at
       http://yourservername:8020/ (or whatever port you choose instead of 8020). That module's indexer has  one
       notable  DWIM feature: it reads over @INC, except that it skips the "." in @INC.  But you can work around
       this by expressing the current directory in some other way than as just  the  single  literal  period  --
       either as some more roundabout way, like so:

         perl -I./. -S podwebserver

       Or by just expressing the current directory absolutely:

         perl -I`pwd` -S podwebserver

       Note that even when "." isn't indexed, the Pod in files under it are still accessible -- just as if you'd
       typed "perldoc whatever" and got the Pod in ./whatever.pl

       This  module  is implemented using many CPAN modules, including: Pod::Simple::HTMLBatch Pod::Simple::HTML
       Pod::Simple::Search Pod::Simple

       See also Pod::Perldoc and <http://search.cpan.org/>

         % podwebserver
         You can now point your browser at http://localhost:8020/