.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Pod::Elemental::Transformer::List 3pm" .TH Pod::Elemental::Transformer::List 3pm "2023-01-04" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Pod::Elemental::Transformer::List \- transform :list regions into =over/=back to save typing .SH "VERSION" .IX Header "VERSION" version 0.102001 .SH "SYNOPSIS" .IX Header "SYNOPSIS" By transforming your Pod::Elemental::Document like this: .PP .Vb 2 \& my $xform = Pod::Elemental::Transfomer::List\->new; \& $xform\->transform_node($pod_document); .Ve .PP You can then produce traditional Pod5 lists by using \f(CW\*(C`:list\*(C'\fR regions like this: .PP .Vb 5 \& =for :list \& * Doe \& a (female) deer \& * Ray \& a drop of golden sun .Ve .PP The behavior of list regions is slighly complex, and described below. .SH "PERL VERSION" .IX Header "PERL VERSION" This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "format_name" .IX Subsection "format_name" This attribute, which defaults to \*(L"list\*(R" is the region format that will be processed by this transformer. .SH "LIST REGION PARSING" .IX Header "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. .PP Lists can be written as a single paragraph beginning \f(CW\*(C`=for :list\*(C'\fR or a region marked off with \f(CW\*(C`=begin :list\*(C'\fR and \f(CW\*(C`=end :list\*(C'\fR. The content allowed in each of those two types is defined by the Pod specification but boils down to this: \*(L"for\*(R" regions will only be able to contain list markers and paragraphs of text, while \*(L"begin and end\*(R" regions can contain arbitrary Pod paragraphs and nested list regions. .PP All lists have a default \f(CW\*(C`indentlevel\*(C'\fR value of 4. Adding \&\f(CW\*(C`:over\*(C'\fR to a \f(CW\*(C`=begin :list\*(C'\fR definition will result in that list having an \f(CW\*(C`indentlevel\*(C'\fR of \f(CW\*(C`n\*(C'\fR instead. (This functionality is not available for lists defined with \f(CW\*(C`=for :list\*(C'\fR.) .PP 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: .PP .Vb 8 \& =for :list \& * Doe \& a deer, \& a female deer \& * Ray \& a drop of golden sun \& or maybe it\*(Aqs a golden \& drop of sun .Ve .PP The above is equivalent to .PP .Vb 1 \& =begin :list \& \& * Doe \& a deer, \& a female deer \& * Ray \& a drop of golden sun \& or maybe it\*(Aqs a golden \& drop of sun \& \& =end :list .Ve .PP It will be transformed into: .PP .Vb 1 \& =over 4 \& \& =item * \& \& Doe \& \& a deer, \& a female deer \& \& =item * \& \& Ray \& \& a drop of golden sun \& or maybe it\*(Aqs a golden \& drop of sun .Ve .PP Which renders as: .IP "\(bu" 4 Doe .Sp a deer, a female deer .IP "\(bu" 4 Ray .Sp a drop of golden sun or maybe it's a golden drop of sun .PP \&\fIrendering ends here\fR .PP In other words: the \fB\f(CB\*(C`*\*(C'\fB\fR 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. .PP .Vb 3 \& =for :list \& * this bullet line \& continues on a second line .Ve .PP Will be transformed into: .PP .Vb 1 \& =over 4 \& \& =item * \& \& this bullet line continues on a second line \& \& =back .Ve .PP Which renders as: .IP "\(bu" 4 this bullet line continues on a second line .PP \&\fIrendering ends here\fR .PP All subsequent lines without markers or leading white space will be kept together as one paragraph. .PP Asterisks mark off bullet list items. Numbered lists are marked off with "\f(CW1.\fR" (or any number followed by a dot). Equals signs mark off definition lists. The markers must be followed by a space. .PP Here's a numbered list: .PP .Vb 4 \& =for :list \& 1. bell \& 2. book \& 3. candle .Ve .PP The choice of number doesn't matter. The generated Pod \f(CW\*(C`=item\*(C'\fR commands will start with 1 and increase by 1 each time. .PP This is rendered as: .IP "1." 4 bell .IP "2." 4 book .IP "3." 4 candle .PP \&\fIrendering ends here\fR .PP 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: .PP .Vb 1 \& =begin :list \& \& = benefits \& \& There are more benefits than can be listed here. \& \& =end :list .Ve .PP Or this input: .PP .Vb 3 \& =for :list \& = benefits \& There are more benefits than can be listed here. .Ve .PP Will become the following output Pod: .PP .Vb 1 \& =over 4 \& \& =item benefits \& \& There are more benefits than can be listed here \& \& =back .Ve .PP Which is rendered as: .IP "benefits" 4 .IX Item "benefits" There are more benefits than can be listed here .PP \&\fIrendering ends here\fR .PP If you want to nest lists, you have to make the outer list a begin/end region, like this: .PP .Vb 1 \& =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 .Ve .PP The inner list, above, could have been written as a compact \*(L"for\*(R" region. .SH "AUTHOR" .IX Header "AUTHOR" Ricardo \s-1SIGNES\s0 .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Alex Peters .IP "\(bu" 4 David Golden .IP "\(bu" 4 Justin Cook .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Ricardo Signes .IP "\(bu" 4 Tomas Doran .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2022 by Ricardo \s-1SIGNES.\s0 .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.