Beefy Boxes and Bandwidth Generously Provided by pair Networks
"be consistent"

Is POD Syntax Obsolete?

by qazwart (Scribe)
on Jun 11, 2013 at 18:10 UTC ( #1038308=perlquestion: print w/replies, xml ) Need Help??
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

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.

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.

Replies are listed 'Best First'.
Re: Is POD Syntax Obsolete?
by tobyink (Abbot) 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
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
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
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.

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

      Maybe the OP meant "obtrusive"?
      لսႽ ᥲᥒ⚪⟊Ⴙᘓᖇ Ꮅᘓᖇ⎱ Ⴙᥲ𝇋ƙᘓᖇ
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.
    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
    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.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://1038308]
Approved by davido
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others avoiding work at the Monastery: (3)
As of 2018-07-21 06:12 GMT
Find Nodes?
    Voting Booth?
    It has been suggested to rename Perl 6 in order to boost its marketing potential. Which name would you prefer?

    Results (444 votes). Check out past polls.