NAME
Web::DataService::PodParser - Pod-to-HTML formatter for Web::DataService
SYNOPSIS
This module is a subclass of Pod::Simple, providing an engine that can parse Pod and generate HTML for use in generating data service documentation pages. It is used as follows:
my $parser = Web::DataService::PodParser->new({ target => 'html', ... });
$parser->parse_string_document($doc_string);
my $doc_html = $parser->output;Several custom data sections are recognized, allowing for directives specific to the Web::DataService system. In addition, formatting codes and ... sections are treated specially.
METHODS
This module provides the following methods:
new ( options )
This class method creates a new instance of the parser. The argument must be an options hash, including any of the following keys:
target
Specifies the format into which the Pod should be translated. Currently, the only value accepted is 'html'.
url_formatter
The value of this attribute should be a code ref. This subroutine will be called once for each URL in the formatted document, and the return value will be substituted for that URL.
css
The value of this attribute should be the URL of a stylesheet, which will be included via an HTML <link> tag. This URL will be passed through the url_formatter if one is specified.
html_header
If specified, this string will be included at the beginning of the HTML output. It should start with <html> and end with a <body> tag. If not specified, this module will generate a header automatically.
html_footer
If specified, this string will be included at the end of the HTML output. It should include </body> and </html>. If not specified, these two closing tags will be appended to the end of the formatted output.
no_tables
If this option has a true value, then Pod lists that are neither numbered nor bulleted will be rendered using the <dl>, <dt>, and <dd> tags. Otherwise, and by default, they will be rendered as tables.
debug
If this option has a true value, then voluminous debugging output will be written to STDERR.
parse_string_document
This method takes a single argument, which must be a string containing Pod text. This text is parsed and formatted into HTML.
output
This method returns the formatted HTML content as a single string, which can then be sent as the body of a response message.
SYNTAX
This module is a subclass of Pod::Simple, and as such can handle all valid Pod syntax. Certain constructs are treated specially, as indicated here:
URLs
When this class is instantiated by Web::DataService::Documentation, it is passed a reference to a URL formatter. This is used to process all ... sections according to the Web::DataService URL specification.
Text formatting
The formatting codes ... and .........
Special directives
Several directives can be included in a Web::DataService documentation page through the use of particular data section identifiers. These either be delimited with =begin and =end, or specified using =for.
wds_node
This directive specifies attributes for the Web::DataService node corresponding to the documentation page on which it appears. This means that you can create documentation pages in the appropriate directory and give them the necessary attributes without having to add define_node calls to your data service application code. For example:
=for wds_node title=General notes about this data servicewds_title
This directive specifies the title for the page. It overrides any value set using =for wds_node or define_node.
$$$
AUTHOR
mmcclenn "at" cpan.org
BUGS
Please report any bugs or feature requests to bug-web-dataservice at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Web-DataService. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
COPYRIGHT & LICENSE
Copyright 2014 Michael McClennen, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.