Ricardo SIGNES > Pod-Elemental-Transformer-List-0.101620 > Pod::Elemental::Transformer::List

Download:
Pod-Elemental-Transformer-List-0.101620.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.101620   Source   Latest Release: Pod-Elemental-Transformer-List-0.102000

NAME ^

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

VERSION ^

version 0.101620

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.

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

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.) All subsequent lines without markers 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.

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

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) 2010 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.

syntax highlighting: