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.

basic_entities

If TRUE encode only basic entities:

  & < >

common_entities

If TRUE encode only common entities:

  & < > á é í ó ú Á É Í Ó Ú â ê î ô û Â Ê Î Ô Û ã õ Ã Õ ç Ç ©

no_generator

If TRUE the meta GENERATOR tag won't be added.

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

Thanks to Ivan Tubert-Brohman <itub@cpan.org> that suggested to add the basic_entities and common_entities options and for tests.

COPYRIGHT

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1115:: Non-ASCII character seen before =encoding in 'á'. Assuming CP1252

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)