/ 
Pod-HtmlEasy-1.0107
River stage one • 1 direct dependent • 1 total dependent
/ Pod::HtmlEasy

NAME

Pod::HtmlEasy - Generate personalized HTML from PODs.

VERSION

This documentation refers to Pod::HtmlEasy version 1.1.7.

DESCRIPTION

The purpose of this module is to generate HTML data from POD in a easy and personalized mode. By default the HTML generated is similar to the CPAN site style for module documentation.

SYNOPSIS

use Pod::HtmlEasy;
my $podhtml = Pod::HtmlEasy->new ( optional local event subs );
my $html = $podhtml->pod2html( 'test.pod' );
print $html;

pod2html ( POD_FILE|FILEHANDLE, HTML_FILE, %OPTIONS )

Convert a POD to HTML. Returns the HTML data generated, as a string or as a list, according to context.

POD_FILE|GLOB

The POD file (file path) or FILEHANDLE (GLOB, opened). The special file handle, DATA is, of course, supported.

If the POD file is "-", or is omitted altogether, input from STDIN is expected, and HTML is written to STDOUT, unless an output file name has been given.

This command shows how to convert POD to HTML on the command line:

C<perl -MPod::HtmlEasy -e'Pod::HtmlEasy->new->pod2html(title,"test.html")' < test.pod > test.html>

or

C<perl -MPod::HtmlEasy -e'Pod::HtmlEasy->new->pod2html("-",title,"test.html")' < test.pod > test.html>

The "title,test" shows how to set parameters to pod2html in this context. Note that there is no "-" preceding the title; if you use one, Perl will complain about an odd number of values in an hash assignment.

HTML_FILE

The default is to use the POD_FILE parameter, replacing the extension with "html" in the current directory. If you want to name the output file differently, use the -output option. Note that this is an incompatible change from previous versions. Sorry 'bout that.

%OPTIONS (optional)

Note that all options have values. Omit the value and you'll get dumped.

body

The body values.

Examples:

## Specify a complete body spec
body => q{alink="#FF0000" bgcolor="#FFFFFF" link="#000000" text="#000000" vlink="#000066"} ,

or:

## This will overwrite only these 2 values. You may also add new key-value combos.
body => { bgcolor => "#CCCCCC" , link => "#0000FF" } ,

Default:

link="#FF0000" bgcolor="#FFFFFF" link="#000000" text="#000000" vlink="#000066"
css

Can be a css file HREF or the css data. The file is distinguished by the fact that the value does not have a newline.

Examples:

css => 'test.css',

## Or:

css => q`
  BODY {
    background: white;
    color: black;
    font-family: arial,sans-serif;
    margin: 0;
    padding: 1ex;
  } ...` ,
index

Define the index data. If not set the index will be generated automatically, calling the event subs on_index_node_start and on_index_node_end. Otherwise, the entire index will be defined by the value of the option, with the exception of the required HTML glue.

index_item

If set (1), =items will be added in the index. =item *, followed by a paragraph can produce some strange indexes. See index_length.

If the =item line ("foo" in =item foo) is an URL (https?://...), whether or not its enclosed in L<>, the http?// is stripped, and a HTML link is created.

index_length

If set (some value) and index_item is set, then the intex line will be restricted to the first space following this number of characters, followed by "..." if appropriate. Default 60 characters.

no_css

If set do not use css.

no_index

If set, do not build and insert the index.

no_generator

If set, the meta GENERATOR tag won't be added.

only_content

If set generate only the HTML content. This implies no_generator and no_css, produces no <body> or <title>, and no DOCTYPE as well, so its really not very good HTML.

output

The file (and path, if desired) to be used to write the outptut HTML.

parserwarn

The backend we use is Pod::Parser. This module generates warnings when it detects badly-formed POD. Regretably, it also generates warnings about multiple blank lines, which can be annoying. Thus, it's disabled by default.

title

The title of the HTML. Default: content of the first =head1 NAME, or, failing that the file path of the output file (if given) or the input file.

top

Set TOP data. The HTML _top will be added just before the index. If there is a value associated with -top (as in -top uArr) That value will be added to to the head1 text. The value should be either a literal character, a representation of a extended HTML character, (as in uArr) or an existing file.

Local Event Subs

So, what are these optional local event subroutines? You have the ability to specify when creating an instance of Pod::HtmlEasy replacements for the subroutines that process the single-letter commands embedded in POD text, such as "B<...>", or the = commands, such as =head1. You may also defined new single-letter commands by providing an event subroutine. Of course, all of the defined commands have implementations. See "Extending POD".

Utility Functions

default_css

Returns the default CSS. To augment, remove the last line, add your changes, and replace the last line.

pm_version ( pod2html )

Return the version of a Perl module file or undef. This is extracted from a statement that looks like "VERSION = 5.0008" Needless to say, this is only avalable after the POD is processed.

pm_package ( pod2html )

Return the package name of the module from which the POD was extracted or undef. Needless to say, this is only avalable after the POD is processed.

pm_name ( pod2html )

Returns what follows the first instance of =head1 NAME description or undef. The description is picked up from what follows NAME on the same line, or from the first nonblank line following the =head1 NAME.

Needless to say, this is only avalable after the POD is processed.

pm_package_version_name ( pod2html )

Returns a list: ( pm_package, pm_version, pm_name ) Needless to say, this is only avalable after the POD is processed.

CHARACTER SET

In compliance with HTML 4.01 specification, Pod::HtmlEasy supports the ISO 8859-1 character set (also known as Latin-1). In essence, this means that the full 8-bit character set is supported.

HTML provides an escape mechanism that allows characters to be specified by name; this kind of specification is called an entity.

Some characters must be converted to entities to avoid confusing user agents. This happens automagically. These characters are: &, <, >, "

HTML (via its relationship with SGML) supports a large number of characters that are outside the set supported by ISO 8859-1. These can be specified in the text by using the E&ls;...&gt; construct. These encodings are defined by ISO 10646, which is semi-informally known as UNICODE. For example, the "heart" symbol E&l;dhearts&gt;. These are listed in section 24.3.1, The list of characters of the HTML 4.01 specification.

EMBEDDED URIs

Pod::HtmlEasy scans text (but not verbatim text!) for embedded URIs, such as http://foo.bar.com that are not embedded in L <...>. Schemes detected are http, https, file and ftp. References of the form foo@bar.com are treated as mailto references and are translated accordingly.

Previous versions handled a more extensive list of URIs. It was thought that the overhead for processing these other schemes was not justified by their utility. That is, not supported by the Firefox browser. YMMV if you're using Internet Explorer!

EXTENDING POD

You can extend POD defining non-standard events.

For example, to enable the command "=hr":

my $podhtml = Pod::HtmlEasy->new(
on_hr => sub {
          my ( $this , $txt ) = @_ ;
          return "<hr>" ;
         }
) ;

To define a new formatting code, do the same thing, but the code must be a single letter.

So, to enable "G<...>":

my $podhtml = Pod::HtmlEasy->new(
on_G => sub {
          my ( $this , $txt ) = @_ ;
          return "<img src='$txt' border=0>" ;
        }
) ;

DEPENDENCIES

This script requires the following modules:

Pod::Parser Pod::ParseLink

Pod::HtmlEasy::Parser Pod::HtmlEasy::Data

Carp English English File::Slurp Regexp::Common Readonly Switch version

DEFAULT CSS

This is the default CSS added to the HTML.

If you want to do your own CSS, use this as base.

BODY {
  background: white;
  color: black;
  font-family: arial,sans-serif;
  margin: 0;
  padding: 1ex;
}
TABLE {
  border-collapse: collapse;
  border-spacing: 0;
  border-width: 0;
  color: inherit;
}
IMG { border: 0; }
FORM { margin: 0; }
input { margin: 2px; }
A.fred {
  text-decoration: none;
}
A:link, A:visited {
  background: transparent;
  color: #006699;
}
TD {
  margin: 0;
  padding: 0;
}
DIV {
  border-width: 0;
}
DT {
  margin-top: 1em;
}
TH {
  background: #bbbbbb;
  color: inherit;
  padding: 0.4ex 1ex;
  text-align: left;
}
TH A:link, TH A:visited {
  background: transparent;
  color: black;
}
A.m:link, A.m:visited {
  background: #006699;
  color: white;
  font: bold 10pt Arial,Helvetica,sans-serif;
  text-decoration: none;
}
A.o:link, A.o:visited {
  background: #006699;
  color: #ccffcc;
  font: bold 10pt Arial,Helvetica,sans-serif;
  text-decoration: none;
}
A.o:hover {
  background: transparent;
  color: #ff6600;
  text-decoration: underline;
}
A.m:hover {
  background: transparent;
  color: #ff6600;
  text-decoration: underline;
}
table.dlsip     {
  background: #dddddd;
  border: 0.4ex solid #dddddd;
}
.pod PRE     {
  background: #eeeeee;
  border: 1px solid #888888;
  color: black;
  padding-top: 1em;
  white-space: pre;
}
.pod H1      {
  background: transparent;
  color: #006699;
  font-size: large;
}
.pod H2      {
  background: transparent;
  color: #006699;
  font-size: medium;
}
.pod IMG     {
  vertical-align: top;
}
.pod .toc A  {
  text-decoration: none;
}
.pod .toc LI {
  line-height: 1.2em;
  list-style-type: none;
}

DIAGNOSTICS

All options must be paired with values

Your argument list (excluding the .pod file if specified) has an odd number of items.

option key is not supported

You've used (mis-spelled?) an unrecognized option.

No file file

We couldn't find that (input) file.

pm_whatever must be referenced through Pod::HtmlEasy

The various pm_ functions are referenced through the module.

The maintainer would appreciate hearing about any messages other than those that result from the use warnings specified for each module.

HtmlEasy uses Pod::Parser, which may produce error messages concerning malformed HTML.

SEE ALSO

Pod::Parser perlpod, perlpodspec.

CONFIGURATION AND ENVIRONMENT

Neither is relevant.

INCOMPATIBILITIES

As of version 1.1, the use of an optional output file as the second parameter, has been replaced with an explicit output option.

BUGS AND LIMITATIONS

Please report problems at RT: http://rt.cpan.org/Public/Bug/Report.html?Queue=Pod-HtmlEasy

AUTHOR

Graciliano M. P. <gm@virtuasites.com.br>

I will appreciate any type of feedback (include your opinions and/or suggestions). ;-P

Thanks to Ivan Tubert-Brohman <itub@cpan.org> that suggested to add the basic_entities and common_entities options and for tests. [These options have been removed. As "modern" browsers don't need all that encoding. See "CHARACTER SET" above.].

Thanks to ITO Nobuaki for the patches for [31784].

Thanks to David Whitcomb for pointing out an error in HTML generation.

MAINTENANCE

Updates for version 0.0803 and subsequent by Geoffrey Leach <gleach@cpan.org>

LICENSE AND COPYRIGHT

Copyright 2004-2006 by M. P. Graciliano
Copyright 2007-2008 by Geoffrey Leach

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