Is POD Syntax Obsolete?

qazwart has asked for the wisdom of the Perl Monks concerning the following question:

I use POD, and use Pod::Usage through out my code. I am familiar with POD syntax. However, the POD syntax strikes me a bit long in the tooth.

POD syntax was created to help developers to quickly write their code. It is fairly straight forward, but there is a learning curve, and teaching developers to use it can be a pain. I like the concept of POD documentation, but I was thinking that it would be much easier to get developers to write the documentation if we could use Markdown for the syntax;

For example, in POD syntax:


=head1 PARAMETERS

The following are valid parameters:

=over 10

=item *

B<-foo>: Does all of your foo stuff.

=item *

B<-bar>: In case you need to bar.

=back
[download]

Would be this in Markdown:


# PARAMETERS

The following are valid parameters:

* **-foo**: Does all of your foo stuff.
* **-bar**: In case you need to bar.
[download]

Markdown is not only easier to write, but is also more readable. And, developers who use Stackoverflow, GitHub, Reddit, SourceForge, and many other sites would be familiar with its syntax.

I'm not thinking of a wholesale replacement, just a way of using Markdown in POD documentation and have tools like POD::Usage and perldoc to be able to parse it.

Comment on Is POD Syntax Obsolete? Select or Download Code

Replies are listed 'Best First'.
Re: Is POD Syntax Obsolete? by tobyink (Canon) on Jun 11, 2013 at 18:46 UTC
Numbered and bullet lists in pod are godawful, but apart from that pod is quite nice, and the =for and =begin commands make it quite extensible. If it's not your cup of tea though, an option is to write in markdown or whatever, and automatically convert to pod for publication. `package Cow { use Moo; has name => (is => 'lazy', default => sub { 'Mooington' }) } say Cow->new->name`	[reply]
Re: Is POD Syntax Obsolete? by toolic (Bishop) on Jun 11, 2013 at 21:00 UTC
A quick search of CPAN might give you some ideas: pod markdown	[reply]
Re: Is POD Syntax Obsolete? by vsespb (Chaplain) on Jun 11, 2013 at 21:31 UTC
I actually find Markdown harder to write for complex documents (with nesting), like this one. And actually going to rewrite it in POD, hope to get something neat like this	[reply]
Re: Is POD Syntax Obsolete? by Laurent_R (Canon) on Jun 11, 2013 at 21:50 UTC
I was tempted to tell you: feel free to write your Markdown to POD conversion module. But, no luck for me (or for you): that already exists.	[reply]
Re: Is POD Syntax Obsolete? (of course not) by Anonymous Monk on Jun 12, 2013 at 03:00 UTC
Is POD Syntax Obsolete? Of course not, its the only syntax supported by perl	[reply]
Re^2: Is POD Syntax Obsolete? (of course not) by choroba (Cardinal) on Jun 12, 2013 at 08:53 UTC
Maybe the OP meant "obtrusive"? لսႽ† ᥲᥒ⚪⟊Ⴙᘓᖇ Ꮅᘓᖇ⎱ Ⴙᥲ𝇋ƙᘓᖇ	[reply]
Re: Is POD Syntax Obsolete? by pemungkah (Priest) on Jun 13, 2013 at 03:40 UTC
POD has you covered. From `perldoc perlpod`: `For, begin, and end will let you have regions of text/code/data that are not generally interpreted as normal POD text, but are passed directly to particular formatters, or are otherwise special. A formatter that can use that format will use the region, otherwise it will be completely ignored.` [download] So you could write a Markdown POD formatter that would look for these and interpret the paragraphs as Markdown. `=begin markdown # PARAMETERS The following are good parameters: * -foo ... =end markdown` [download] Since the text is otherwise ignored if the formatter doesn't know how to handle it, you don't get weird-looking stuff in your output if this runs through the usual POD formatter.	[reply] [d/l] [select]