NAME

       Pod::Webserver -- Minimal web server for local Perl documentation

SYNOPSIS

         % podwebserver
         ...
         You can now open your browser to http://localhost:8020/

DESCRIPTION

       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.

       "podwebserver -h" displays help:

               Pod::Webserver version 3.06
                Running under perl version 5.018002 for linux
               Usage:
                 podwebserver                   = Start podwebserver on localhost:8020. Search @INC
                 podwebserver -p 1234           = Start podwebserver on localhost:1234
                 podwebserver -p 1234 -H blorp  = Start podwebserver on blorp:1234
                 podwebserver -t 3600           = Auto-exit in 1 hour. Default => 86000 (24 hours)
                                                      0 => No timeout, but does not work for me
                 podwebserver -d /path/to/lib   = Ignore @INC, and only search within /path/to/lib
                 podwebserver -e /path/to/skip  = Exclude /path/to/skip files
                 podwebserver -q                = Quick startup (but no Table of Contents)
                 podwebserver -v                = Run with verbose output to STDOUT
                 podwebserver -h                = See this message
                 podwebserver -V                = Show version information

               Run 'perldoc Pod::Webserver' for more information.

SECURITY (AND @INC)

       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 whose Pod 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.)

   ON INDEXING '.' 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

SEE ALSO

       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/>

COPYRIGHT AND DISCLAIMERS

       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.

Repository

       <https://github.com/ronsavage/Pod-Webserver>

AUTHOR

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

       Maintained by: Allison Randal "allison@perl.org" and Ron Savage "ron@savage.net.au".