On Mon, Nov 11, 2002 at 01:40:59PM -0600, Garrett Goebel wrote: > The general Pro's and Con's of POD seem to be: > > PRO > === > simple, concise, limited, extensible, forgiving > easy to convert to XXX, easy to write, easy to read, easy to ignore > separates block/inline markup, no special editor required > the camel was written in it, the powers that be won't stand for any substitute > > CON > === > confusing, Perl-centric, limited, no tables, no figures, no lists > whitespace sensitivity, separates block/inline markup > extensiblity loses most other "PRO" args
Two arguments that I don't see listed (and may not have been raised in the most recent perl6-language version of the debate) are: [PRO] It is difficult to get open source hackers to write documentation. Therefore, it is essential to reduce the potential barriers as much as possible. Format conversion can happen after the fact; the best format in the world is useless if it inhibits people from writing docs. Pod addresses this as a core problem, and imposes only the smallest of learning curves and slightest of inconveniences upon authors. [CON] Anything more complex than pod either inhibits people writing docs, or inhibits docs being converted to other formats (HTML, [La]TeX, XML, DocBook, etc.), or both. This point is more than just theory; we've seen it happen many times over the past decade. Another argument in favor of Pod is that it seems that everyone who wants to switch to format XXX hasn't made a significant contribution to the Perl documentation (or the Pod toolchain), yet finds it horribly broken. Nevertheless, the number of people who use Pod and the amount of documentation in Pod continues to increase every year. Z.
