NAME

DocSet::Source::POD - A class for parsing input document in the POD format

SYNOPSIS

DESCRIPTION

META: not sure if the customized implementation of L<> belongs here. But it works as follows:

Assuming that the main config.cfg specifies the following argument:

     dir => {
             ...
  
             # search path for pods, etc. must put more specific paths first!
             search_paths => [qw(
                 docs/2.0/api/mod_perl-2.0 
                 docs/2.0/api/ModPerl-Registry 
                 docs/2.0 
                 docs/1.0
                 .
             )],
  
             # what extensions to search for
             search_exts => [qw(pod pm html)],
  
            },  

Whenever the pod includes Title, the code will first convert foo::bar into foo/bar and then will try to find the file foo/bar.pod in the search path (similar to @INC), as well as files foo/bar.pm and foo/bar.html under dir src. If other search_exts are specified they will be searched as well. If there is a much the link will be created, otherwise only the title of the link will be displayed.

Notice that the search_paths must specify more specific paths first. If you don't they won't be searched. Currently this is done only to optimize memory usage and some speed, not sure if that's very important. But this is different from how Perl does search with @INC since DocSet reads all the files in memory once and then reuses this data.

METHODS

retrieve_meta_data()

parse_pod()

podify_items()

  podify_items();

Podify text to represent items in pod, e.g:

  1 Some text from item Item1
  
  2 Some text from item Item2

becomes:

  =over 4
 
  =item 1
 
  Some text from item Item1

  =item 2
 
  Some text from item Item2

  =back

podify_items() accepts '*' and digits as bullets

podify_items() receives a ref to array of paragraphs as a parameter and modifies it. Nothing returned.

Moreover, you can use a second level of indentation. So you can have

  * title

  * * item

  * * item

or

  * title

  * 1 item

  * 2 item

where the second mark is which tells whether to use a ball bullet or a numbered item.

head2page_breaks

in the slides_mode we want each =headX to start a new slide, so this mode inserts the page-breaks:

  =for html <?page-break>

starting from the second header (well actually from the third in the raw POD, because the first one (NAME) gets stripped before it's seen by the rendering engine.

AUTHORS

Stas Bekman <stas (at) stason.org>