NAME
Pod::Simple::XHTML -- format Pod as validating XHTML
SYNOPSIS
use Pod::Simple::XHTML;
my $parser = Pod::Simple::XHTML->new();
...
$parser->parse_file('path/to/file.pod');DESCRIPTION
This class is a formatter that takes Pod and renders it as XHTML validating HTML.
This is a subclass of Pod::Simple::Methody and inherits all its methods. The implementation is entirely different than Pod::Simple::HTML, but it largely preserves the same interface.
METHODS
Pod::Simple::XHTML offers a number of methods that modify the format of the HTML output. Call these after creating the parser object, but before the call to parse_file:
my $parser = Pod::PseudoPod::HTML->new();
$parser->set_optional_param("value");
$parser->parse_file($file);perldoc_url_prefix
In turning Foo::Bar into http://whatever/Foo%3a%3aBar, what to put before the "Foo%3a%3aBar". The default value is "http://search.cpan.org/perldoc?".
perldoc_url_postfix
What to put after "Foo%3a%3aBar" in the URL. This option is not set by default.
title_prefix, title_postfix
What to put before and after the title in the head. The values should already be &-escaped.
html_css
$parser->html_css('path/to/style.css');The URL or relative path of a CSS file to include. This option is not set by default.
html_javascript
The URL or relative path of a JavaScript file to pull in. This option is not set by default.
html_doctype
A document type tag for the file. This option is not set by default.
html_header_tags
Additional arbitrary HTML tags for the header of the document. The default value is just a content type header tag:
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">Add additional meta tags here, or blocks of inline CSS or JavaScript (wrapped in the appropriate tags).
default_title
Set a default title for the page if no title can be determined from the content. The value of this string should already be &-escaped.
force_title
Force a title for the page (don't try to determine it from the content). The value of this string should already be &-escaped.
html_header, html_footer
Set the HTML output at the beginning and end of each file. The default header includes a title, a doctype tag (if html_doctype is set), a content tag (customized by html_header_tags), a tag for a CSS file (if html_css is set), and a tag for a Javascript file (if html_javascript is set). The default footer simply closes the html and body tags.
The options listed above customize parts of the default header, but setting html_header or html_footer completely overrides the built-in header or footer. These may be useful if you want to use template tags instead of literal HTML headers and footers or are integrating converted POD pages in a larger website.
If you want no headers or footers output in the HTML, set these options to the empty string.
index
Whether to add a table-of-contents at the top of each page (called an index for the sake of tradition).
SUBCLASSING
If the standard options aren't enough, you may want to subclass Pod::Simple::XHMTL. These are the most likely candidates for methods you'll want to override when subclassing.
handle_text
This method handles the body of text within any element: it's the body of a paragraph, or everything between a "=begin" tag and the corresponding "=end" tag, or the text within an L entity, etc. You would want to override this if you are adding a custom element type that does more than just display formatted text. Perhaps adding a way to generate HTML tables from an extended version of POD.
So, let's say you want add a custom element called 'foo'. In your subclass's new method, after calling SUPER::new you'd call:
$new->accept_targets_as_text( 'foo' );Then override the start_for method in the subclass to check for when "$flags->{'target'}" is equal to 'foo' and set a flag that marks that you're in a foo block (maybe "$self->{'in_foo'} = 1"). Then override the handle_text method to check for the flag, and pass $text to your custom subroutine to construct the HTML output for 'foo' elements, something like:
sub handle_text {
my ($self, $text) = @_;
if ($self->{'in_foo'}) {
$self->{'scratch'} .= build_foo_html($text);
} else {
$self->{'scratch'} .= $text;
}
}idify
my $id = $pod->idify($text);
my $hash = $pod->idify($text, 1);This method turns an arbitrary string into a valid XHTML ID attribute value. The rules enforced, following http://webdesign.about.com/od/htmltags/a/aa031707.htm, are:
The id must start with a letter (a-z or A-Z)
All subsequent characters can be letters, numbers (0-9), hyphens (-), underscores (_), colons (:), and periods (.).
Each id must be unique within the document.
In addition, the returned value will be unique within the context of the Pod::Simple::XHTML object unless a second argument is passed a true value. ID attributes should always be unique within a single XHTML document, but pass the true value if you are creating not an ID but a URL hash to point to an ID (i.e., if you need to put the "#foo" in <a href="#foo">foo</a>.
SEE ALSO
Pod::Simple, Pod::Simple::Methody
COPYRIGHT
Copyright (c) 2003-2005 Allison Randal.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This library 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.
AUTHOR
Allison Randal <allison@perl.org>