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.
I had the same frustration, and wrote Pod::WikiDoc 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
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 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 Markdown, please let me know and we can chat by email.
-- dagolden
Re:Seen Pod::Wikidoc?
bart on 2009-02-17T08:55:29
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 translator tools, and have the exact markup syntax rules be configurable? So that, for example, your module could be used to convert Markdown, or any other wiki-like dialect, to POD.
That would be neat. And yeah, I wouldn't mind spending time working on it.
BTW what kind of markup syntax would you propose for DL/DT/DD lists? I'm thinking of something like:
* descriptive title:
This is the text
explaining the conceptRe:Seen Pod::Wikidoc?
dagolden on 2009-02-17T12:24:15
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. That's something new from RJBS, but it might prove a better platform for a general tool.
But if you want to look at refactoring Pod::WikiDoc into a more general tool, please feel free.
On DL/DT/DD markup, the RT ticket discusses this kind of markup, which I think other wiki-style engines use:
; foo : This is a description of foo
I like your style visually, tough. I have to think about what it would be like to parse unambiguously in Parse::RecDescent. (What Pod::WikiDoc uses internally.)
-- dagolden
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.
