Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

bart (450)

Journal of bart (450)

Monday February 09, 2009
11:22 PM

From markdown to POD

[ #38445 ]

The verbose and arcane syntax of POD always distracts me from what I want to write, whenever I write POD directly. I prefer markdown, which doesn't get in the way.

And with going from markdown through html2pod, I get a reasonable headstart. It works pretty well.

The one thing I commonly need in POD that markdown is lacking, is itemized bulleted lists, that in HTML you'd write with DL/DT/DD lists, and in POD you write as

=over

=item one

This is item one.

=item two

This is item two.

=back

(Gah! POD is ghastly!)

In a reference manual, I need them a lot.

But, starting from a plain bulleted list, you can get the basic POD list syntax, and by just tweaking the generated POD a little (replacing the bullets with the item text), I get where I want.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • I had the same frustration, and wrote Pod::WikiDoc [cpan.org] so I could write in a Kwiki-like format and have it converted to Pod. Bullets are like this:

    * item 1
    * item 2

    I wrote up a lightning talk about it: http://dagolden.com/files/pod-wikidoc.pdf [dagolden.com]

    Unfortunately, it doesn't do DT/DD style lists yet, but mostly because I haven't gotten around to adding it. A request for it [cpan.org] has been in the RT queue for a while.

    If you're interested in patching in support and using WikiDoc instead of rolling your own system around Ma

    • Looking at the POD of your module, I can see you have the exact same beef with POD as I have.

      But, IMHO, there are already just too many similar yet slightly different markup languages out there. I don't feel like learning yet another dialect; I'd just end up getting confused. And they all have their own translators. For example, your Wikidoc format is very much like Markdown, with probably the largest differences between them in the format of the links.

      Do you think it would be feasible to unify those transl

      • I think generalizing the framework -- parsing POD in *.pm for a block of some style and "compiling" it to .pod -- is possible. (I'm currently working on an "inline" style that just appends the proper POD at the end of the *.pm). It would need to have the actual parsing/translating code extracted into either a plugin or a subclass.

        There are others thinking about this, too. See, for example, Pod-Weaver [cpan.org]. That's something new from RJBS, but it might prove a better platform for a general tool.

        But if you want

  • There is always a fine line to tread between being too simple and being too complex to be usable. Like you I think Markdown is a nice language and being external to Perl or any particular wiki it's independence is a strength.

    --
    -- "It's not magic, it's work..."