There's already a perfectly good documentation format for Perl that has a much less bletcherous syntax. It's POD.
Now POD has its flaws, as anyone who's ever written a book in it will argue (and several of the people who've done so are actually on the Perl 6 design team), but it's also fairly nice in what it does include and how it does it.
Hmmm, it seems I've mentioned YAML quite often lately. (Although I'm not really sure whether two entries count as "quite often" even if so close in time.) Now, it may seem OT to mention it in this thread too. But your points gave me the chance to expose a meditation that's been in my head for some time now. Now, both YAML and POD are LWMLs. As it happens, LWMLs are typically divided in two categories of which each of them is part respectively: namely, data serialization oriented and presentation oriented ones.
XML, for example, is suitable both for presentation and data serialization. But it sure is not lightweight. Now, I'm not really asking about merging (something based on) POD with (something based on) YAML. But I'd be interested in the feasability of an actual lightweight markup that could be suitable both for presentation and for data serialization. A first remark that one may make is that there are good reasons to keep logically different things, ehm, different. But it's also true that document description involves very similar issues to those that one can find in data serialization, e.g. wrt sectional divisions or special lists and many other things. So solving the problem once may be enough. Solving it in a way that is both forgiving enough for one task, and precise enough for the other IMHO would mean to achieve flexibility and reliability. Provided that it's possible, but then that's why I'm asking here...
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
Read Where should I post X? if you're not absolutely sure you're posting in the right place.
Please read these before you post! —
Posts may use any of the Perl Monks Approved HTML tags:
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
- a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.
| & || & |
| < || < |
| > || > |
| [ || [ |
| ] || ] ||