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

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