POD Document Object Model design
To detail the form that "standard" POD forms take in terms of Kwid::DOM::Node objects.
standard
The multitude of POD parsers out there could all do with something of a "standard" POD form, other than those loosely made up by the collection of Pod to XML formatters for Perl 5. Actually, not "other" but "closely resembling" and "standardised".
This document details the DTD / Schema of "standard" POD documents, and the mechanism by which "dialects" can plug in non-standard nodes.
See Kwid::Preprocessor for details on how those non-standard nodes are converted into standard nodes for output.
The below schema is a "Zen" cut of a POD to DocBook (in fact, ORA dblite) node types. "Zen" means, I am just writing down what I think is a good design without considering the alternate implementations yet.
This structure will change heavily, this is an early draft, actually draft is perhaps overstatings its greatness, this is actually still a brainfart.
The level of detail that this schema goes is one of those pragmatic trade-offs between richness in interoperability, and simplicity of design. At this stage, this document is leaning so far on the side of interoperability, it's damn well almost fallen over!
Note that all POD formatters will need to do something with all of these blocks. They can also expect the Pod::Preprocessor not to fire any events to them that do not match this DTD.
id
Blocks can have unique identifiers for various uses.
class
The formatter(s) that will want to do something special with this node. This is a space seperated list of formatter names.
Note that it is possible for a single node at the beginning of a document with this set to affect the entire rest of the document on output, depending on the nature of the dialect.
This can be considered roughly equivalent to the old =for FOO syntax.
=for FOO
source
In "extenuating circumstances", normative XML output might actually specify the text that went along with a particular block. Note that this does not include the source text that went along with the child content or nodes.
Whether or not this safe round-tripping to XML is ever considered "worth it" will be considered after a proof-of-concept implementation. As is the case with Pod::SAX (IIRC), this feature may be dropped.
The para node type starts a normal paragraph that otherwise hasn't been wrapped.
para
Content of paragraphs can only be inline blocks, like Text nodes or inline styles.
node for verbatim blocks
With a little departure from the flat nature of POD, these nodes will represent an entire section of the manual page - ie, until the start of the next sect with an equal or lower number.
sect
Content of paragraphs can only be blocks elements, like title element or paragraphs.
A container for the heading styles for sect1..sect4 blocks.
sect1
sect4
Used for unnumbered lists. Think ul. May only contain listitems, and possibly a title.
ul
Used for numeric lists. Think ol. May only contain listitems, and possibly a title.
ol
Entries for itemizedlist and orderedlists. May only contain block-level things, like paragraphs.
itemizedlist
orderedlist
Used for glossaries (definition lists). Think dl. May only contain glossary terms and definitions, and possibly a title.
dl
Entries for glosslist. This represents the term. May only contain block-level things, like paragraphs.
glosslist
Entries for glosslist. This represents the definition of a term. May only contain block-level things, like paragraphs.
DocBook imports for tables.
Various O'Reilly DocBook types that just seem ... fitting. Should these go in? You be the judge - come to #perlkwid on irc.freenode.net
Hmm, maybe draw `standard' nodes for documenting class syntax?
Various styles of warning blocks. I really like these.
A named point that can be referred to.
name
name of the anchor.
Anything that doesn't match this DTD, or nodes that do not match this DTD will be considered a travesty by the Pod::Preprocessor. They will be fed into the class, or perhaps wiped up by some active processor.
I've gone and included the whole ORA safari inline styles list, because I like richness in these things. I think there should be lots of these :).
Note that inline elements can have class attributes, just like block elements.
What you get from I< >
I< >
What you get from F< >
F< >
What you get from C< >
C< >
A link might be the only "special" inline style. It has one extra attribute;
link
The target of the link.
S< >
non-breaking spaces will be represented in the character stream as such. `standard' POD may still support this escape.
Slt >
I suppose we'll still have to support this, but consider the warn block level elements for putting things.
warn
Xlt >
Link targets! Hmm, well, I don't see why not...
The following works were used as reference material and input. Or, rather, if you're reading this SVN revision, then this is my shortlist of reference material to work with in ensuring maximum design compatibility with these usages of POD.
Matt Seargeant. SAX interface to POD documents. Nice one Matt!
A crucial reference work... as POD is thought to be quite similar to DocBook in many ways. We shall see how well the mapping works...
O'Reilly & Associates. See also apt-get install docbook-defguide
apt-get install docbook-defguide
Used to clarify some decisions made.
Another reference POD XML generator to compare output form and structure with.
Examined closely as a prior art for building the linking syntax for POD.
Two example modules that want to be able to use the parser to extract certain information, for differing uses.
Checking to see whether any of the concepts introduced by OODoc need any special support from the Pod parser. This will be used more as a "final check" - as if the design is "right", or at least "not utterly ballsed up", then usages like this shouldn't need any special support to implement their magic.
Then you wouldn't need a special POD formatter to parse and output OODoc! Or, rather, the dialect-special POD parser would parse it and preprocessor would transform the document at the right time. Maybe.
Well, it's the goal, anyway.
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
Expected text after =item, not a bullet
To install Perl6::Pugs, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Perl6::Pugs
CPAN shell
perl -MCPAN -e shell install Perl6::Pugs
For more information on module installation, please visit the detailed CPAN module installation guide.