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
bart (450)
Monday February 09, 2009
11:22 PM
From markdown to POD
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
Loading... please wait.
help them think they understand.
--Larry Wall
Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.
Seen Pod::Wikidoc? (Score:1)
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:
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
Re: (Score:2)
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
Re: (Score:1)
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
Fine line (Score:2)
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..."