.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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::Abstract::BuildNode 3pm"
.TH Pod::Abstract::BuildNode 3pm "2020-05-17" "perl v5.30.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::Abstract::BuildNode \- Build new nodes for use in Pod::Abstract.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Pod::Abstract::BuildNode qw(node nodes); # shorthand
\& 
\& my $root_doc = node\->root;
\& for(my $i = 1; $i < 10; $i ++) {
\&    $root_doc\->push(node\->head1("Heading number $i"));
\& }
\& print $root_doc\->pod;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
For building a new Pod::Abstract document, or adding nodes to an
existing one. This provides easy methods to generate correctly set
nodes for most common Pod::Abstract elements.
.SH "NOTES"
.IX Header "NOTES"
Pod::Abstract::BuildNode can export two functions, \f(CW\*(C`node\*(C'\fR and
\&\f(CW\*(C`nodes\*(C'\fR. These are constant functions to provide a shorthand so
instead of writing:
.PP
.Vb 3
\& use Pod::Abstract::BuildNode;
\& # ...
\& my @nodes = Pod::Abstract::BuildNode\->from_pod( $pod );
.Ve
.PP
You can instead write:
.PP
.Vb 3
\& use Pod::Abstract::BuildNode qw(node nodes);
\& # ...
\& my @nodes = nodes\->from_pod($pod);
.Ve
.PP
Which is more readable, and less typing. \f(CW\*(C`node\*(C'\fR and \f(CW\*(C`nodes\*(C'\fR are both
synonyms of \f(CW\*(C`Pod::Abstract::BuildNode\*(C'\fR.
.PP
This shorthand form is shown in all the method examples below. All
methods operate on the class.
.SH "METHODS"
.IX Header "METHODS"
.SS "from_pod"
.IX Subsection "from_pod"
.Vb 1
\& my @nodes = nodes\->from_pod($pod_text);
.Ve
.PP
Given some literal Pod text, generate a full subtree of nodes. The
returned array is all of the top level nodes. The full document tree
will be populated under the returned nodes.
.SS "root"
.IX Subsection "root"
.Vb 1
\& my $root = node\->root;
.Ve
.PP
Generate a root node. A root node generates no output, and is used to
hold a document tree. Use this to make a new document.
.SS "begin"
.IX Subsection "begin"
.Vb 1
\& my $begin_block = node\->begin($command);
.Ve
.PP
Generates a begin/end block. Nodes nested inside the begin node will
appear between the begin/end.
.PP
Note that there is no corresponding \f(CW\*(C`end\*(C'\fR method \- the end command
belongs to it's corresponding begin.
.SS "for"
.IX Subsection "for"
.Vb 1
\& my $for = node\->for(\*(Aqoverlay from <class>\*(Aq);
.Ve
.PP
Create a =for node. The argument is the literal body of the for node,
no parsing will be performed.
.SS "paragraph"
.IX Subsection "paragraph"
.Vb 1
\& my $para = node\->paragraph(\*(AqPod text\*(Aq);
.Ve
.PP
Generates a Pod paragraph, possibly containing interior sequences. The
argument will be parsed as Pod, and will generate text and sequence
nodes inside the paragraph.
.SS "verbatim"
.IX Subsection "verbatim"
.Vb 1
\& my $v = node\->verbatim($text);
.Ve
.PP
Add the given text as a verbatim node to the document. All lines in
the fiven \f(CW$text\fR will be indented by one space to ensure they are
treated as verbatim.
.SS "heading"
.IX Subsection "heading"
.Vb 1
\& my $head2 = node\->heading(2, $heading);
.Ve
.PP
Generate a heading node at the given level. Nodes that \*(L"belong\*(R" in the
heading's section should be nested in the heading node. The
\&\f(CW$heading\fR text will be parsed for interior sequences.
.SS "head1"
.IX Subsection "head1"
.Vb 1
\& node\->head1($heading);
.Ve
.SS "head2"
.IX Subsection "head2"
.Vb 1
\& node\->head2($heading);
.Ve
.SS "head3"
.IX Subsection "head3"
.Vb 1
\& node\->head3($heading);
.Ve
.SS "head4"
.IX Subsection "head4"
.Vb 1
\& node\->head4($heading);
.Ve
.SS "over"
.IX Subsection "over"
.Vb 1
\& my $list = node\->over([$num]);
.Ve
.PP
Generates an over/back block, to contain list items. The optional
parameter \f(CW$num\fR specifies the number of spaces to indent by. Note
that the back node is part of the over, there is no separate back
method.
.SS "item"
.IX Subsection "item"
.Vb 1
\& my $item = node\->item(\*(Aq*\*(Aq);
.Ve
.PP
Generates an item with the specified label. To fill in the text of the
item, nest paragraphs into the item. Items should be contained in over
nodes.
.SS "text"
.IX Subsection "text"
.Vb 1
\& my $text = node\->text(\*(AqLiteral text\*(Aq);
.Ve
.PP
Generates a literal text node. You generally \fBdo not\fR want this, you
probably want a paragraph. Use this if you want to, for example,
append a word at the end of a paragraph.
.SS "pod"
.IX Subsection "pod"
.Vb 1
\& my $n = node\->pod;
.Ve
.PP
Generates an \*(L"=pod\*(R" command. Can be useful to force pod mode at the
end of cut nodes.
.PP
Do not confuse with \*(L"from_pod\*(R"!
.SH ""
.IX Header ""
.Vb 1
\& my $cut = node\->cut;
.Ve
.PP
Generates an explicit \*(L"=cut\*(R" command.
.SH "AUTHOR"
.IX Header "AUTHOR"
Ben Lilburne <bnej@mac.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2009 Ben Lilburne
.PP
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.