NAME

PodWEB - a simple CGI script displaying P.O. Documents.

DESCRIPTION

This simple script is similar in function to the well-known perldoc.perl.org or perldoc.pl while adhering to the K.I.S.S. (keep it simple, soldier) principle. Assuming that one has a working HTTPd/CGI environment, the deployment is as simple as copying the repository to the destination directory and/or adjusting the configuration file. It runs in a bare Perl 5.20+ environment.

The script accepts two variables from the URL string:

v (version): indicates the library path where PODs are taken from; if empty, then the currently running Perl include path is considered;
s (search): is the search keyword; if it resembles a module name, then it is looked for in the version-dependent search path; otherwise, a configurable search through the documents is performed.

Searching

PodWEB performs these steps whenever a page is searched for through the use of the search box:

Module by that name is looked up and its POD content is displayed. This is similar in function to a plain perldoc call.
If function search is enabled, then the string is looked up in perlfunc's index and the browser is redirected directly to the matching tag. Prepending the query with a question mark (?) will cause PodWEB to start from this step.
If the built-in variable search is enabled, then the string is looked for in perlvar's index and the matching tag is displayed.
If module name search is enabled, then the matching parts of all module names are reported. This is the first stage when the results page is shown instead of redirecting the user to a POD. Prepending the query with a double question mark (??) makes PodWEB start from here and always display the search results page.
If the module index search is enabled, then any matching index entries (X<> tags) are shown.
If text search is enabled, then all POD content is scanned. The matching modules are shown along with part of the paragraph where the phrase is found.

The browser

Enabling the text search activates the module browser. It is similar to perldoc's Core modules section except that it displays all modules available within the include path.

The browser can be reached by clicking the a-z button in the search bar.

It accepts two variables from the query string – the Perl version/include path (v) and the first letter the module name starts with (p).

Table support

PodWEB supports rendering tables formatted similarly to the psql(1) output with two enhancements:

multicolumn cells are also supported by simply skipping the column mark |,
multiple separator lines may be included.

It is also capable of setting character-based alignment through the text-align with character CSS property although there is no browser supporting this.

Tables must be put in a verbatim (indented) block. Note that the separator line is one character longer than the content on both sides.

The following code:

 Header  | Header  | Header
---------+---------+---------
 Content | Content | Content
 Multicolumn       | Content
 Multi  +| Content | Content
 row    +|         |
 content |         |
(3 rows)
Time: 1 s

creates the table:

Header	Header	Header
(3 rows)
Time: 1 s
Content	Content	Content
Multicolumn		Content
Multi row content	Content	Content

Syntax highlighting

If a syntax highlighting engine is turned on, then the POD renderer will process any verbatim blocks that look like Perl code with that library. The non-standard =for syntax language command enables the given language for the next verbatim block. For example:

=for syntax sql

    SELECT * FROM dual;

highlights SQL keywords:

SELECT * FROM dual;

The =for syntax none command turns syntax rendering off.

`config`

The file called config contains the following settings:

query.length.max

The maximum length of a request query item. The default is 128 characters and that corresponds to the maxlength value for the search input element in the default HTML template.

page.default

The page that is displayed when the search box is empty. The default is perl.

page.html

The name of the template file to be used for page rendering. Defaults to page.html.

cache.age.max

This setting controls the Cache-Control HTTP header. It adjusts the maximum cache time (in seconds) at the proxy/browser side. The default is 300 seconds (5 minutes).

cache.int.dir

Internal cache dir. If set, then the rendered pages and content aggregation caches are saved in that directory. This option is required for advanced search functions to work. There is no default value here: the pages are not cached until you add this setting to the configuration.

cache.int.max

Internal cache expiry time in seconds. The cached content becomes invalid after that time and will be rendered again. The default is 600 seconds.

cache.search.max

Full-text search cache expiry time in seconds. The cache regeneration process will be launched after that time. The default value is 3600 (1 hour).

search.perlfunc

Whether the search through perlfunc should be done if no module is found. The search will look for the given phrase in the index entries and redirect directly to that tag. This is turned off by default.

search.perlvar

Enables searching for the given string in perlvar's index if no module or no perlfunc tag by that name is found. The user will be automatically redirected if a matching index key is found. Default is off.

search.names

Search for parts of module names. The text displayed depends on the number of names found. The user will be presented with either a CPAN search link or a number of options. Requires cache.int.dir to work. Default is off.

search.index

This switch enables the generation and searching in the indexes of the POD pages in the include path. Requires cache.int.dir to work. The index keys are acquired from the X<> tags. Default is off.

search.all

This enables the generation and searching in the textual content of all POD pages in the search path. It will display the links to the pages and configurable amount of the text below. Requires cache.int.dir to work. It is turned off by default.

search.all.before.num

The number of characters ahead of search phrase shown in the text search results. The default is 100 characters.

search.all.after.num

The number of characters after the search phrase shown in the results. The default is 100 characters.

search.abstract.max

The abstract line (the contents of the HEAD section) is shown in the browser next to the module name. It is supposed to be a short description of the package, however, some creators put a lot more than it is necessary for there.
The default limit is 300 characters.

syntax.engine

Turn on syntax highlighting. The argument selects the highlighting engine:

perltidy: uses the Perl::Tidy module which is the basis of the perltidy utility (only Perl syntax is supported),
sourcehighlight: uses Syntax::SourceHighlight library.

Highlighting is turned off by default.

string.rtime

Text to be displayed in place of ${rtime} for newly rendered pages. The default is “rendered in ..s”.

string.cached

Text displayed in place of ${rtime} for cached pages. The default is “retrieved from cache in ..s”.

string.error.title

Page title when an error is detected. The default is simply Error.

string.error.name

The description of the error page. The default is Page rendering error.

string.error.text

The actual error text on the page. %s is replaced with the exception thrown by the renderer. The default value is “Cannot get the information you requested. The error was: %s”.

string.search.title

Search page title. The %s tag is replaced with the searched phrase. The default value is Search results.

string.search.name

Search page description. %s is replaced with the searched phrase. The default is simply %s.

string.search.notfound

The text that is displayed when nothing is found. %s is replaced with the search string. The default is header Not found followed by the text saying The phrase ... you were looking for could not be found.

string.search.names

The text displayed before the list of module names found. The default value is the header titled Modules and POD pages.

string.search.dym

The text displayed if exactly one module is found. The first %s is replaced with the link target to the module found. The second is the module name itself. The default text sais Did you mean ...?

string.search.nomodules

The text displayed if no module names were found. The two %s contain HTML encoded and URL encoded search strings. By default, it contains a link redirecting to meta::cpan search – No modules or POD pages found. Search for ... at meta::cpan instead.

string.search.fts

Full-text search header. The default value is header named Text search.

string.search.index

The text displayed before index search results. The default for this is simply Index.

string.opt.default

The text displayed in the unmodified page.html as the default Perl version. Normally it is default (version).

string.logo

The logo displayed in the top-left corner of the page. Defaults to the PodWEB SVG logo and some text below.

link.in_to

Whether the subsection links be appended with POD page name. It is enabled by default which follows perldoc's behaviour. For example, L<Module/Section> will be rendered as Section in Module when turned on, and just Section when off.

link.man

The link for the manual pages. The first %s is man section number and the second is the name of the man page. By default, all man requests go to linux.die.net/man.

path.perl version

The path.* options contain include paths for Perl versions or POD sources available for browsing. Apart from this, the running Perl include path will also be available as default and it can also be redefined.

HTML SOURCE

The page.html file contains the HTML skeleton used to render the page. Variable parts of the document are marked with the dollar sign and curly brackets (i.e. ${content}.)

All variables coming from the query string are available in addition to the following:

${module}: indicates the module name or subpage that is loaded,
${module_version}: the version number extracted from our $VERSION or similar statement in the module,
${title}: document summary, the first paragraph of the NAME section,
${title_dash}: expands to the long dash character (—) if the title is defined,
${version}: current running Perl version,
${options}: the selection of defined sets of documents,
${logo}: the contents of the string.logo configuration value,
${extra_links}: additional links at the top of the page; there is only one at the moment, the module browser,
${content}: the generated POD content,
${date}: current date and time,
${rtime}: rendering time,
${site_css}: if the site.css file is found in the working directory, then this variable is filled with HTML stylesheet link element.

If the variable name is prepended with the # character, then its content is quoted with HTML meta tags. For example:

<input name="s" value="${#s}" maxlength="100">

quotes the user-supplied string s rendering the exact text in the browser.

AUTHOR

Originally written and maintained by Matlib (matlib@matlibhax.com), any comments or suggestions are welcome.

LICENCE

THIS SOFTWARE IS IN PUBLIC DOMAIN

There is no limitation on any kind of usage of this code. You use it because it is yours.