PAF(1p) User Contributed Perl Documentation PAF(1p)NAME
paf - Pod Abstract Filter. Transform Pod documents from the command line.
SYNOPSIS
sh$>
paf summary /usr/bin/paf
paf add_podcmds SomeModule.pm
paf sort -heading=METHODS Pod/Abstract/Node.pm # METHODS is default
paf sort summary Pod/Abstract/Node.pm
# See Pod::Abstract::Filter::overlay
paf overlay sort cut clear_podcmds SomeClass.pm
# -p will emit pod source, instead of spawning perldoc.
paf -p sort Pod::Abstract::Node
paf -p find hoist Pod::Abstract::Node
DESCRIPTION
Paf is a small but powerful, modular Pod filter and transformation tool. It allows full round-trip transformation of Pod documents using
the Pod::Abstract library, with multiple filter chains without having to serialise/re-parse the document at each step.
Paf comes with a small set of useful filters, but can be extended by simply writing new classes in the "Pod::Abstract::Filter" namespace.
FILTERS
add_podcmds
Add explicit =pod commands at the end of each cut section, so that all pod sections are started with an =pod command.
clear_podcmds
Remove all =pod commands that are not ending cut blocks. This will clean up documents that have been reduced using the "cut" filter too.
cut
Remove all cut nodes, so that only the pod remains.
overlay
paf overlay Source.pm
For overlay to work, there must be a "begin :overlay/end :overlay" section in the Source file, with "=overlay SECTION Module" definitions
inside. The net effect is that any missing subheadings in SECTION are added from the same section in the specified Modules.
Note that this will overlay the whole subheading, INCLUDING CUT NODES, so it can add code to the source document. Use "cut" if you don't
want this.
Each overlaid section will include a "=for overlay from" marker, so that it can be replaced by a subsequent overlay from the same
file/module. These sections will be replaced in-place, so ordering of sections once first overlaid will be preserved.
unoverlay
paf unoverlay Source.pm
Strips all sections marked as overlaid and matching the overlay spec from the source.
sort
paf sort [-heading=METHODS] Source.pm
Sort all of the subheadings in the named heading (METHODS if not provided).
This will move cut nodes around with their headings, so your code will mutate. Use "cut" if you only want pod in the output.
Alternatively, you can also cause sorting of headings to occur by including "=for sorting" at the start of your section (before the first
subheading).
summary
Provide an abbreviated summary of the document. If there is a verbatim node in the body of a heading containing the heading name, it will
be considered an example and expanded as part of the summary.
find
paf find [-f=]name Source.pm
Find specific sub-sections or list items mentioning name. Used to restrict a larger document down to a smaller set that you're interested
in. If no -f is specified, then the word following find will be the search term.
uncut
paf uncut Source.pm
Convert cut nodes in the source into verbatim text. Not the inverse of cut!
number_sections
paf number_sections Source.pm
Applies simple multipart (3.1.2) section numbering to head1 through head4 headings.
Note that number_sections will currently stuff up some of the cleverness in things like summary, as the section names won't match function
names any more.
perl v5.10.1 2010-01-03 PAF(1p)
Check Out this Related Man Page
Pod::Abstract(3pm) User Contributed Perl Documentation Pod::Abstract(3pm)NAME
Pod::Abstract - Abstract document tree for Perl POD documents
SYNOPSIS
use Pod::Abstract;
use Pod::Abstract::BuildNode qw(node);
# Get all the first level headings, and put them in a verbatim block
# at the start of the document
my $pa = Pod::Abstract->load_filehandle(*STDIN);
my @headings = $pa->select('/head1@heading');
my @headings_text = map { $_->pod } @headings;
my $headings_node = node->verbatim(join "
",@headings_text);
$pa->unshift( node->cut );
$pa->unshift( $headings_node );
$pa->unshift( node->pod );
print $pa->pod;
DESCRIPTION
POD::Abstract provides a means to load a POD (or POD compatible) document without direct reference to it's syntax, and perform
manipulations on the abstract syntax tree.
This can be used to support additional features for POD, to format output, to compile into alternative formats, etc.
WHY?
If you've ever asked yourself "What does Pod do for me?", this module is intended to answer that question.
While Pod looks like a simple format, the specification calls for a number of special cases to be handled, and that makes any software that
works on Pod as text more complex than it needs to be.
In addition to this, Pod does not lend itself to a natural structured model. This makes it difficult to manipulate without damaging the
validity of the document.
Pod::Abstract solves these problems by loading the document into a structured tree, and providing consistent traversal, searching,
manpulation and re-serialisation. Pod related utilities are easy to write using Pod::Abstract.
The design goal of Pod::Abstract is to do the hard work for the programmer - the library should work for you, and as such it should be
significantly easier than string mashing what you want out of a Pod document.
PROCESSING MODEL
The intent with POD::Abstract is to provide a means to decorate a parse tree, rather than manipulate text, to allow other software to add
features and functionality to POD based documenation systems.
If you wish to write modules that interact nicely with other POD::Abstract modules, then you should provide a POD::Abstract ->
POD::Abstract translation. Leave any document element that your program is not interested in directly untouched in the parse tree, and if
you have data that could be useful to other packages, decorate the parse tree with that data even if you don't see any direct way to use it
in the output.
In this way, when you want one more feature for POD, rather than write or fork a whole translator, a single inline "decorator" can be
added.
The "paf" utility provides a good starting point, which also allows you to hook in to an existing filter/transform library. Simply add a
"Pod::Abstract::Filter" class to the namespace and it should start working as a "paf" command.
EXAMPLE
Suppose you are frustrated by the verbose list syntax used by regular POD. You might reasonably want to define a simplified list format for
your own use, except POD formatters won't support it.
With Pod::Abstract you can write an inline filter to convert:
* item 1
* item 2
* item 3
into:
=over
=item *
item 1
=item *
item 2
=item *
item 3
=back
This transformation can be simply performed on the document tree. If your formatter does not use Pod::Abstract, you can simply pipe out POD
and use a regular formatter. If your formatter supports Pod::Abstract though, then you can feed in the syntax tree directly without having
to re-serialise and parse the document.
In addition to this, because the source document is still valid Pod, you aren't breaking compatibility with regular perldoc just by making
Pod::Abstract transformations.
POD SUPPORT
Pod::Abstract aims to support all POD rules defined in perlpodspec (even the ones I don't like), except for those directly related to
formatting output, or which cannot be implemented generically.
COMPONENTS
Pod::Abstract is comprised of:
o The parser, which loads a document tree for you.
You should access this through "Pod::Abstract", not directly
o The document tree, which is the root node you are given by the parser. Calling pod on the root node should always give you back your
original document.
See Pod::Abstract::Node
o Pod::Abstract::Path, the node selection expression language. This is generally called by doing "$node->select(PATH_EXP)".
Pod::Abstract::Path is the most complex and powerful component of this module, and if you're not using it you should be. ;)
This allows you to ask questions like:
"In the first head1 that starts with "A", find me the head2 matching 'foo' with bold text somewhere in the preceding paragraph or
heading"
/head1[@heading=~{^A}](0)/head2[@heading=~{foo}i]<<head2 :paragraph[//:B]
You probably don't need anything that complex, but it's there if you do.
o The node builder, Pod::Abstract::BuildNode
METHODS
load_file
my $pa = Pod::Abstract->load_file( FILENAME );
Read the POD document in the named file. Returns the root node of the document.
load_filehandle
my $pa = Pod::Abstract->load_file( FH );
Load a POD document from the provided filehandle reference. Returns the root node of the document.
load_string
my $pa = Pod::Abstract->load_string( STRING );
Loads a POD document from a scalar string value. Returns the root node of the document.
AUTHOR
Ben Lilburne <bnej@mac.com>
COPYRIGHT AND LICENSE
Copyright (C) 2009 Ben Lilburne
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl v5.10.1 2010-01-03 Pod::Abstract(3pm)