Pod::Webserver(3pm)

✨ NAME ✨

Pod::Webserver — bestie, it's a minimal web server for local Perl documentation. That's the whole thing. Tiny server, big vibes. 💖

---

🌸 SYNOPSIS 🌸

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

Like. That's it. That's the whole launch sequence. Run it, open the browser, slay. 🦋

---

🎀 DESCRIPTION 🎀

Okay so this module can be run as an application that works as a minimal web server to serve local Perl documentation. It's literally like perldoc except it works through your browser. Same energy, but glowier. ✨

And podwebserver -h displays help, which looks exactly like this:

        Pod::Webserver version 3.11
         Running under perl version 5.020002 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.

Not me just handing you the whole help text verbatim. Iykyk. 👑

---

🔒 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. It stays in its lane. 🫶

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. Lowkey a flex, highkey a leak. 💀

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" — iconic clarification, honestly) 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. Set the vibe before you set the server. 🌈

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. Rude, honestly. 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. So like, not indexed ≠ not reachable. Bestie math. 🧮✨

---

👀 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.

No cap, that warranty disclaimer is doing a lot of heavy lifting. Read it, bestie. 💀

🌟 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".

---

okay that's the whole page, you ate that 💅 — this was perl v5.32.0, dated 2021-01-08, and it lives in the Pod::Webserver(3pm) section. Go open that browser and stan your own local docs. Periodt. 🎀💖✨