NAME

Pod::HtmlEasy - Generate easy and personalizable HTML from POD, without extra modules and on "the flight".

DESCRIPTION

The purpose of this module is to generate HTML data from POD in a easy and personalizable mode.

By default the HTML generated is simillar to CPAN style for modules documentations.

USAGE

Simple usage:

my $podhtml = Pod::HtmlEasy->new() ;

my $html = $podhtml->pod2html( 'test.pod' ) ;

print "$html\n" ;

Complete usage:

use Pod::HtmlEasy ;

## Create the object and set my own events subs:
## ** Note that here are all the events, and examples of how to implement **
## ** them, and actually this are the default events, soo you don't need  **
## ** to set everything.                                                  **

my $podhtml = Pod::HtmlEasy->new(
on_head1     => sub {
                  my ( $this , $txt , $a_name ) = @_ ;
                  return "<a name='$a_name'></a><h1>$txt</h1>\n\n" ;
                } ,

on_head2     => sub {
                  my ( $this , $txt , $a_name ) = @_ ;
                  return "<a name='$a_name'></a><h2>$txt</h2>\n\n" ;
                } ,

on_head3     => sub {
                  my ( $this , $txt , $a_name ) = @_ ;
                  return "<a name='$a_name'></a><h3>$txt</h3>\n\n" ;
                } ,

on_B         => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<b>$txt</b>" ;
                } ,

on_C         => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<font face='Courier New'>$txt</font>" ;
                } ,

on_E         => sub {
                  my ( $this , $txt ) = @_ ;
                  return '<' if $txt =~ /^lt$/i ;
                  return '>' if $txt =~ /^gt$/i ;
                  return '|' if $txt =~ /^verbar$/i ;
                  return '/' if $txt =~ /^sol$/i ;
                  return chr($txt) if $txt =~ /^\d+$/ ;
                  return $txt ;
                }

on_I         => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<i>$txt</i>" ;
                } ,

on_L         => sub {
                  my ( $this , $L , $text, $page , $section, $type ) = @_ ;
                  if   ( $type eq 'pod' ) {
                    $section = "#$section" if $section ne '' ;
                    return "<i><a href='http://search.cpan.org/perldoc?$page$section'>$text</a></i>" ;
                  }
                  elsif( $type eq 'man' ) { return "<i>$text</i>" ;}
                  elsif( $type eq 'url' ) { return "<a href='$page' target='_blank'>$text</a>" ;}
                } ,
                
on_F         => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<b><i>$txt</i></b>" ;
                }

on_S         => sub {
                  my ( $this , $txt ) = @_ ;
                  $txt =~ s/\n/ /gs ;
                  return $txt ;
                }

on_Z         => sub { return '' ; }

on_verbatin  => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<pre>$txt</pre>\n" ;
                } ,

on_textblock => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<p>$txt</p>\n" ;
                } ,

on_over      => sub {
                  my ( $this , $level ) = @_ ;
                  return "<ul>\n" ;
                } ,

on_item      => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<li>$txt</li>\n" ;
                } ,

on_back      => sub {
                  my $this = shift ;
                  return "</ul>\n" ;
                } ,
                
on_for       => sub { return '' ;}

on_include   => sub {
                  my ( $this , $file ) = @_ ;
                  return "./$file" ;
                }

on_uri       => sub {
                  my ( $this , $uri ) = @_ ;
                  return "<a href='$uri' target='_blank'>$uri</a>" ;
                }

on_error     => sub {
                  my ( $this , $txt ) = @_ ;
                  return "<!-- POD_ERROR: $txt -->" ;
                } ,

on_index_node_start => sub {
                         my ( $this , $txt , $a_name , $has_childs ) = @_ ;
                         my $ret = "<li><a href='#$a_name'>$txt</a>\n" ;
                         $ret .= "\n<ul>\n" if $has_childs ;
                         return $ret ;
                       } ,

on_index_node_end => sub {
                       my $this = shift ;
                       my ( $txt , $a_name , $has_childs ) = @_ ;
                       my $ret = $has_childs ? "</ul>" : '' ;
                       return $ret ;
                     } ,

) ;

## Convert to HTML:

my $html = $podhtml->pod2html('test.pod' , 'test.html' ,
title => 'POD::Test' ,
body => { bgcolor => '#CCCCCC' } ,
css => 'test.css' ,
) ;

METHODS

new ( %EVENTS_SUBS )

By default the object has it own subs to handler the events.

But if you want to personalize/overwrite them you can set this keys in the initialization:

(For examples of how to implement the event subs see "USAGE" above).

on_head1 ( $txt , $a_name )

When =head1 is found.

$txt: The text of the command.
$a_name: The text of the command filtered to be used as <a name="$a_name"</a>>.

on_head2 ( $txt , $a_name )

When =head2 is found. See on_head1.

on_head3 ( $txt , $a_name )

When =head2 is found. See on_head1.

on_B ( $txt )

When B<...> is found. (bold text).

on_C ( $txt )

When C<...> is found. (code text).

on_E ( $txt )

When E<...> is found. (a character escape).

on_I ( $txt )

When I<...> is found. (italic text).

on_L ( $L , $text, $page , $section, $type )

When L<...> is found. (Link).

$L: The link content. This is what is parsed to generate the other variables.
$text: The link text.
$page: The page of the link. Can be an URI, pack::age, or some other reference.
$section: The section of the $page.
$type: The type of the link: pod, man, url.

on_F ( $txt )

When I<...> is found. (used for filenames).

on_S ( $txt )

When I<...> is found. (text contains non-breaking spaces).

on_Z ( $txt )

When I<...> is found. (a null (zero-effect) formatting code).

on_verbatin ( $txt )

When VERBATIN data is found.

on_textblock ( $txt )

When normal text blocks are found.

on_over ( $level )

When =over X is found.

on_item ( $txt )

When =item foo is found.

on_back

When =back is found.

on_for

When =for is found.

By default '=for' is ignored!

on_include ( $file )

When =include is found.

Should be used only to handle the localtion of the $file.

on_uri ( $uri )

When an URI (URL, E-MAIL, etc...) is found.

on_error ( $txt )

Called on POD syntax error occurrence.

on_index_node_start ( $txt , $a_name , $has_childs )

Called to build the INDEX. This is called when a node is start.

$has_childs can be used to know if the node has childs (sub-nodes).

on_index_node_end ( $txt , $a_name , $has_childs )

Called to build the INDEX. This is called when a node ends.

$has_childs can be used to know if the node has childs (sub-nodes).

pod2html ( POD_FILE|POD_DATA|FILEHANDLER , HTML_FILE , %OPTIONS )

Convert a POD to HTML. Also returns the HTML data generated.

POD_FILE|POD_DATA|GLOB

The POD file (file path) , data (SCALAR) or FILEHANDLER (GLOB opened).

HTML_FILE (optional)

The output HTML file path.

** Note that the method also returns the HTML data generated, soo you also can use it wihtout generate files.

%OPTIONS (optional)

title

The title of the HTML.

** Default: file path

body

The body values.

Examples:

body => q`alink="#FF0000" bgcolor="#FFFFFF" link="#000000" text="#000000" vlink="#000066"` ,

## Or:

body => { bgcolor => "#CCCCCC" , link => "#0000FF" } , ## This will overwrite only this 2 values,
                                                       ## the other default values are kept.

** Default: alink="#FF0000" bgcolor="#FFFFFF" link="#000000" text="#000000" vlink="#000066"

css

Can be a css file path (HREF) or the css data.

Examples:

css => 'test.css' ,

## Or:

css => q`
  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;
  }
` ,

top

Set a TOP data. The HTML paste with top will be added just before the index.

index

Set the index data. If not set will generate automatically, calling the events subs on_index_node_start and on_index_node_end

no_index

If TRUE tell to not build and insert the index.

no_css

If TRUE tell to not use css.

only_content

If TRUE tell to only generate the HTML content (between <body>...</body>).

index_item

If TRUE items will be added in the index.

pm_version ( FILE )

Return the version of a Perl Module file.

pm_package ( FILE )

Return the package name of a Perl Module file.

pm_name

Returns =head1 NAME description.

pm_package_version_name

Returns all the 3 values at the same time.

default_css

Returns the default CSS.

EXTENDING POD

You can extend POD seting not standart events.

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

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

To enable formatters is the same thing, but will accept only one letter.

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

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

DEFAULT CSS

This is the default CSS added to the HTML.

** If you will set 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;
}

AUTHOR

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

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

COPYRIGHT

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

To install Pod::HtmlEasy, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Pod::HtmlEasy

CPAN shell

perl -MCPAN -e shell
install Pod::HtmlEasy

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)