NAME

POD Document Object Model design

PURPOSE

To detail the form that "standard" POD forms take in terms of Kwid::DOM::Node objects.

INTRODUCTION

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.

POD SCHEMA

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.

BLOCK ELEMENTS

BLOCK COMMON ATTRIBUTES

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.

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.

para

The para node type starts a normal paragraph that otherwise hasn't been wrapped.

content

Content of paragraphs can only be inline blocks, like Text nodes or inline styles.

programlisting

node for verbatim blocks

content

Content of paragraphs can only be inline blocks, like Text nodes or inline styles.

sect1 .. sect4

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.

content

Content of paragraphs can only be blocks elements, like title element or paragraphs.

title

A container for the heading styles for sect1..sect4 blocks.

content

Content of paragraphs can only be inline blocks, like Text nodes or inline styles.

itemizedlist

Used for unnumbered lists. Think ul. May only contain listitems, and possibly a title.

orderedlist

Used for numeric lists. Think ol. May only contain listitems, and possibly a title.

listitem

Entries for itemizedlist and orderedlists. May only contain block-level things, like paragraphs.

glosslist

Used for glossaries (definition lists). Think dl. May only contain glossary terms and definitions, and possibly a title.

glossterm

Entries for glosslist. This represents the term. May only contain block-level things, like paragraphs.

glossdef

Entries for glosslist. This represents the definition of a term. May only contain block-level things, like paragraphs.

note: new stuff follows

table

thead

tfoot

tbody

colspec

spanspec

row

entry

DocBook imports for tables.

name

synopsis

description

Various O'Reilly DocBook types that just seem ... fitting. Should these go in? You be the judge - come to #perlkwid on irc.freenode.net

classname

funcsynopsis

Hmm, maybe draw `standard' nodes for documenting class syntax?

caution

important

note

tip

warning

Various styles of warning blocks. I really like these.

anchor

A named point that can be referred to.

name

name of the anchor.

anything else

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.

INLINE ELEMENTS

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.

abbrev

acronym

citation

citetitle

emphasis

What you get from I< >

firstterm

foreignphrase

glossterm

quote

subscript

superscript

filename

What you get from F< >

function

command

literal

What you get from C< >

parameter

symbol

type

varname

classname

option

optional

userinput

link

A link might be the only "special" inline style. It has one extra attribute;

ref

The target of the link.

MISC NOTES

What about S< >?

non-breaking spaces will be represented in the character stream as such. `standard' POD may still support this escape.

What about Slt >?

I suppose we'll still have to support this, but consider the warn block level elements for putting things.

What about Xlt >?

Link targets! Hmm, well, I don't see why not...

BIBLIOGRAPHY

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.

Pod::SAX

Matt Seargeant. SAX interface to POD documents. Nice one Matt!

Pod::DocBook

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

DocBook, the definitive Guide

O'Reilly & Associates. See also apt-get install docbook-defguide

Used to clarify some decisions made.

Pod::XML

Another reference POD XML generator to compare output form and structure with.

Pod::XPath

Examined closely as a prior art for building the linking syntax for POD.

Test::Inline

Test::Pod::Coverage

Two example modules that want to be able to use the parser to extract certain information, for differing uses.

OODoc

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.