Pod::Simplify - Simplify the pod (Plain Old Documentation) portion of a file
use Pod::Simplify; $p = new Pod::Simplify; $p->parse_from_file_by_name(FILENAME, CALLBACK);
These are markups that are accepted. Several are introduced as internal markup, but their use in regular pod is encouraged to help the cross-referencing process.
C<> = Code B<> = Bold I<> = Italics V<> = Variable P<> = Function/Procedure S<> = Switch F<> = Filename M<> = Manpage X<> = Index mark R<> = Hyperreference to anything L<> = Link to anything (old-style reference) W<> = Single word (non-breaking spaces) Z<> = No-space E<> = HTML Escape U<> = Unchanged/verbatim =without auto-indexing =with full-item-indexing =without man-warnings
The with/without commands are really generalized variable set/unset commands.
=with X of Y and
=without X are the general forms.
Y defaults to 1.
The new =head is generalized to any heading level. Alternate forms are
=begin =end =over =back =item =cut =pod =comment
Each comment is presented to the formatter so that, if possible, it can be included in the final file as an invisible comment.
Which should have a syntax similar to , if it were done.
Opposite of =cut.
Q&D array dumper
Wrap incoming text by turning spaces into newlines.
DO NOT FEED TABS!
Given text with a possible reference in it, using a reference form of
Something(s) for some manual section s (Fails for section 3g) Something;SomethingElse Something/SomethingElse
return a complex set of nested arrays.
Return TEXT if no references are found in it.
Constructor for Simplify objects
Method to parse a pod file, and either return the results as one big array, or invoke a callback every interval
Given flowed text, return an ASCII equivalent missing formatting.
Given STRING, break it into possibly multiple elements, escaping HTML special characters.
Sheer magic. (Undocumented technology, that is...)
Preparation and entry function for flowed2().
Return the result of flowed2() in an array.
Set up the object before parsing the file.
Convert a block of text to the new style of markup. The heuristics are specific to Perl and the existing Perl documentation.
(This code probably isn't reliable yet. The idea is to convert old style implicit references into new sytle explicit references using . Then the formatter simply has to look do references based on fields.)
Perform specific heuristics on the =head portion. The NAME first level header causes an index to this manpage entry. Other headers generate local indices.
The interesting bits. If DUMP-SUB is defined, it'll be invoked with each parsed record. If not, the parsed records will be returned when all records derived from this paragraph are complete.
(This is the code that takes a paragraphs worth of data and parses it into an internal representation, possible invoking the above heuristic code to add formatting.
The list/listbegun/listpending stuff is, while functional, quite badly done, and needs a complete rewrite from a more stable perspective. There are actually two goals that are currently wrapped up in one implementation. First, we need to be able to keep track of block (=begin/=end) environments, and secondly we need to be able to keep a pending queue (FIFO) of parsed paragraphs if we are in a situation where we don't have enough information to finish parsing a current paragraph. This happens with lists, for example, because we can't deduce the type of the list (which is returned in both the begin and end records) until we see the first paragraph of text for that list.)
Post-file method to finish off anything that got started but didn't get closed down.
Returns the resulting material.