NAME

       Pod::Elemental::Transformer::List - transform :list regions into =over/=back to save
       typing

VERSION

       version 0.102000

SYNOPSIS

       By transforming your Pod::Elemental::Document like this:

         my $xform = Pod::Elemental::Transfomer::List->new;
         $xform->transform_node($pod_document);

       You can then produce traditional Pod5 lists by using ":list" regions like this:

         =for :list
         * Doe
         a (female) deer
         * Ray
         a drop of golden sun

       The behavior of list regions is slighly complex, and described below.

ATTRIBUTES

   format_name
       This attribute, which defaults to "list" is the region format that will be processed by
       this transformer.

LIST REGION PARSING

       There are three kinds of lists: numbered, bulleted, and definition.  Every list must be
       only one kind of list.  Trying to mix list styles will result in an exception during
       transformation.

       Lists can be written as a single paragraph beginning "=for :list" or a region marked off
       with "=begin :list" and "=end :list".  The content allowed in each of those two types is
       defined by the Pod specification but boils down to this: "for" regions will only be able
       to contain list markers and paragraphs of text, while "begin and end" regions can contain
       arbitrary Pod paragraphs and nested list regions.

       All lists have a default "indentlevel" value of 4.  Adding ":over<n>" to a "=begin :list"
       definition will result in that list having an "indentlevel" of "n" instead.  (This
       functionality is not available for lists defined with "=for :list".)

       Ordinary paragraphs in list regions are scanned for lines beginning with list item markers
       (see below).  If they're found, the list is broken into paragraphs and markers.  Here's a
       demonstrative example:

         =for :list
         * Doe
         a deer,
         a female deer
         * Ray
         a drop of golden sun
         or maybe it's a golden
         drop of sun

       The above is equivalent to

         =begin :list

         * Doe
         a deer,
         a female deer
         * Ray
         a drop of golden sun
         or maybe it's a golden
         drop of sun

         =end :list

       It will be transformed into:

         =over 4

         =item *

         Doe

         a deer,
         a female deer

         =item *

         Ray

         a drop of golden sun
         or maybe it's a golden
         drop of sun

       Which renders as:

       •   Doe

           a deer, a female deer

       •   Ray

           a drop of golden sun or maybe it's a golden drop of sun

       rendering ends here

       In other words: the "*" indicates a new bullet.  The rest of the line is made into one
       paragraph, which will become the text of the bullet point when rendered.  (Yeah, Pod is
       weird.) To continue the text of the bullet point on more than one line, start subsequent
       lines with white space.

         =for :list
         * this bullet line
           continues on a second line

       Will be transformed into:

         =over 4

         =item *

         this bullet line continues on a second line

         =back

       Which renders as:

       •   this bullet line continues on a second line

       rendering ends here

       All subsequent lines without markers or leading white space will be kept together as one
       paragraph.

       Asterisks mark off bullet list items.  Numbered lists are marked off with "1." (or any
       number followed by a dot).  Equals signs mark off definition lists.  The markers must be
       followed by a space.

       Here's a numbered list:

         =for :list
         1. bell
         2. book
         3. candle

       The choice of number doesn't matter.  The generated Pod "=item" commands will start with 1
       and increase by 1 each time.

       This is rendered as:

       1.  bell

       2.  book

       3.  candle

       rendering ends here

       Definition lists are unusual in that the text on the line after a item marker will be used
       as the bullet, rather than the next paragraph.  So this input:

         =begin :list

         = benefits

         There are more benefits than can be listed here.

         =end :list

       Or this input:

         =for :list
         = benefits
         There are more benefits than can be listed here.

       Will become the following output Pod:

         =over 4

         =item benefits

         There are more benefits than can be listed here

         =back

       Which is rendered as:

       benefits
           There are more benefits than can be listed here

       rendering ends here

       If you want to nest lists, you have to make the outer list a begin/end region, like this:

         =begin :list

         * first outer item

         * second outer item

         =begin :list

         1. first inner item

         2. second inner item

         =end :list

         * third outer item

         =end :list

       The inner list, above, could have been written as a compact "for" region.

AUTHOR

       Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 by Ricardo SIGNES.

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