perlpodspec - Plain Old Documentation: format specification and notes
This document is detailed notes on the Pod markup language. Most people will only have to
read perlpod to know how to
write in Pod, but this document may answer some incidental questions to do with parsing and
rendering Pod.
In this document, "must" / "must not", "should" / "should
not", and "may" have their conventional (cf. RFC 2119) meanings: "X must do
Y" means that if X doesn't do Y, it's against this specification, and should really be
fixed. "X should do Y" means that it's recommended, but X may fail to do Y, if there's
a good reason. "X may do Y" is merely a note that X can do Y at will (although it is
up to the reader to detect any connotation of "and I think it would be nice if X did
Y" versus "it wouldn't really bother me if X did Y").
Notably, when I say "the parser should do Y", the parser may fail to do Y, if the
calling application explicitly requests that the parser not do Y. I often phrase this as
"the parser should, by default, do Y." This doesn't require the parser to
provide an option for turning off whatever feature Y is (like expanding tabs in verbatim
paragraphs), although it implicates that such an option may be provided.
perlpod, perlsyn/"PODs:
Embedded Documentation", podchecker
Sean M. Burke
|
|
