/ 
Pod-POM-Web-1.24
River stage one • 2 direct dependents • 2 total dependents
/ Pod::POM::Web

NAME

Pod::POM::Web - HTML Perldoc server

DESCRIPTION

Pod::POM::Web is a Web application for browsing the documentation of Perl components installed on your local machine. Since pages are dynamically generated, they are always in sync with code actually installed.

The application offers

  • a tree view for browsing through installed modules (with dynamic expansion of branches as they are visited)

  • a tree view for navigating and opening / closing sections while visiting a documentation page

  • a source code view with hyperlinks between used modules and optionally with syntax coloring (see section "Optional features")

  • direct access to perlfunc entries (builtin Perl functions)

  • search through perlfaq headers

  • full-text search, including names of Perl variables (this is an optional feature -- see section "Optional features").

  • parsing and display of version number

  • display if and when the displayed module entered Perl core.

  • parsing pod links and translating them into hypertext links

  • links to CPAN sites

The application may be hosted by an existing Web server, or otherwise may run its own builtin Web server.

The DHTML code for navigating through documentation trees requires a modern browser. So far it has been tested on Microsoft Internet Explorer 8.0, Firefox 3.5, Google Chrome 3.0 and Safari 4.0.4.

USAGE

Usage is described in a separate document Pod::POM::Web::Help.

INSTALLATION

Starting the Web application

Once the code is installed (most probably through CPAN or CPANPLUS), you have to configure the web server :

As a mod_perl service

If you have Apache2 with mod_perl 2.0, then edit your perl.conf as follows :

PerlModule Apache2::RequestRec
PerlModule Apache2::RequestIO
<Location /perldoc>
      SetHandler modperl
      PerlResponseHandler Pod::POM::Web->handler
</Location>

Then navigate to URL http://localhost/perldoc.

As a cgi-bin script

Alternatively, you can run this application as a cgi-script by writing a simple file perldoc in your cgi-bin directory, containing :

#!/path/to/perl
use Pod::POM::Web;
Pod::POM::Web->handler;

Make this script executable, then navigate to URL http://localhost/cgi-bin/perldoc.

The same can be done for running under mod_perl Registry (write the same script as above and put it in your Apache/perl directory). However, this does not make much sense, because if you have mod_perl Registry then you could as well run it as a basic mod_perl handler.

As a standalone server

A third way to use this application is to start a process invoking the builtin HTTP server :

perl -MPod::POM::Web -e server

This is useful if you have no other HTTP server, or if you want to run this module under the perl debugger. The server will listen at http://localhost:8080. A different port may be specified, in several ways :

perl -MPod::POM::Web -e server 8888
perl -MPod::POM::Web -e server(8888)
perl -MPod::POM::Web -e server -- --port 8888

Opening a specific initial page

By default, the initial page displayed by the application is perl. This can be changed by supplying an open argument with the name of any documentation page: for example

http://localhost:8080?open=Pod/POM/Web
http://localhost:8080?open=perlfaq

Setting a specific title

If you run several instances of Pod::POM::Web simultaneously, you may want them to have distinct titles. This can be done like this:

perl -MPod::POM::Web -e server -- --title "My Own Perl Doc"

MISCELLANEOUS

Note about security

This application is intended as a power tool for Perl developers, not as an Internet application. It will give access to any file installed under your @INC path or Apache lib/perl directory (but not outside of those directories); so it is probably a bad idea to put it on a public Internet server.

Optional features

Syntax coloring

Syntax coloring improves readability of code excerpts. If your Perl distribution is from ActiveState, then Pod::POM::Web will take advantage of the ActiveState::Scineplex module which is already installed on your system. Otherwise, you need to install PPI::HTML, available from CPAN.

Full-text indexing

Pod::POM::Web can index the documentation and source code of all your installed modules, including Perl variable names, Names:::Of::Modules, etc. To use this feature you need to

HINTS TO POD AUTHORING

Images

The Pod::Pom::Web server also serves non-pod files within the @INC hierarchy. This is useful for example to include images in your documentation, by inserting chunks of HTML as follows :

=for html
  <img src="pretty_diagram.jpg">

or

=for html
  <object type="image/svg+xml" data="try.svg" width="640" height="480">
  </object>

Here it is assumed that auxiliary files pretty_diagram.jpg or try.svg are in the same directory than the POD source; but of course relative or absolute links can be used.

METHODS

handler

Pod::POM::Web->handler($request, $response, $options);

Public entry point for serving a request. Objects $request and $response are specific to the hosting HTTP server (modperl, HTTP::Daemon or cgi-bin); $options is a hashref that can contain

page_title

for specifying the HTML title of the application (useful if you run several concurrent instances of Pod::POM::Web).

port

the HTTP port listening for requests

module_dirs

directories for searching for modules, in addition to the standard ones installed with your perl executable.

<script_dirs>

additional directories for searching for scripts

server

Pod::POM::Web->server($port, $options);

Starts the event loop for the builtin HTTP server. The $port number can be given as optional first argument (default is 8080). The second argument $options may be used to specify a page title (see "handler" method above).

This function is exported into the main:: namespace if perl is called with the -e flag, so that you can write

perl -MPod::POM::Web -e server

Options and port may be specified on the command line :

perl -MPod::POM::Web -e server -- --port 8888 --title FooBar

ACKNOWLEDGEMENTS

This web application was deeply inspired by :

  • the structure of HTML Perl documentation released with ActivePerl (http://www.activeperl.com/ASPN/Perl).

  • the excellent tree navigation in Microsoft's former MSDN Library Web site -- since they rebuilt the site, keyboard navigation has gone !

  • the standalone HTTP server implemented in Pod::WebServer.

  • the wide possibilities of Andy Wardley's Pod::POM parser.

Thanks to Philippe Bruhat who mentioned a weakness in the API, to Chris Dolan who supplied many useful suggestions and patches (esp. integration with AnnoCPAN), to Rémi Pauchet who pointed out a regression bug with Firefox CSS, to Alexandre Jousset who fixed a bug in the TOC display, to Cédric Bouvier who pointed out a IO bug in serving binary files, to Elliot Shank who contributed the "page_title" option, to Olivier 'dolmen' Mengué who suggested to export "server" into main::, to Ben Bullock who added the 403 message for absent modules, and to Paul Cochrane for several improvements in the doc and in the repository structure.

RELEASE NOTES

Indexed information since version 1.04 is not compatible with previous versions.

So if you upgraded from a previous version and want to use the index, you need to rebuild it entirely, by running the command :

perl -MPod::POM::Web::Indexer -e "index(-from_scratch => 1)"

AUTHOR

Laurent Dami, <dami AT cpan DOT org>

COPYRIGHT & LICENSE

Copyright 2007-2021 Laurent Dami, all rights reserved.

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

TODO

- real tests !
- factorization (esp. initial <head> in html pages)
- use Getopts to choose colouring package, toggle CPAN, etc.
- declare Pod::POM bugs
    - perlre : line 1693 improper parsing of L<C<< (?>pattern) >>>
 - bug: doc files taken as pragmas (lwptut, lwpcook, pip, pler)
 - exploit doc index X<...>
 - do something with perllocal (installation history)
 - restrict to given set of paths/ modules
     - need to change toc (no perlfunc, no scripts/pragmas, etc)
     - treenav with letter entries or not ?
- port to Plack