On Thu, 2005-03-17 at 02:17 -0800, Brent 'Dax' Royal-Gordon wrote: > David Storrs <[EMAIL PROTECTED]> wrote: > > Aside from links, that's pretty much the entire perlpodtut boiled down > > into 7 bullets; a little experimentation to get the hang of it and it > > all holds together nicely, easy to remember. > > Yes, yes, yes. Pod is one of the things Perl 5 did almost exactly right.
Absolutely, and that's why I'd like to see more POD details preserved. > It's simple, intuitive, and stays out of your way. It gives you most of > the formatting primitives you actually *need*, and nicely balances the > need for easy-to-remember and easy-to-type formatting codes with the > need to avoid using them on accident. It's a very clean, > low-punctuation format, which makes it visually distinctive from the > surrounding code. This is the spirit in which I've absorbed some of Kwid into my proposal only where it supports those goals. I've removed some extra formatting characters because I thought that they added too many chances for overlap with real documentation. I've also searched my local PODs to see where AJS Kwid would overlap POD and cause problems (6.4% of my local PODs, for example, start some lines with "*", which would be a minor, but notable problem, but 13.1% start a line with "-" which is a larger problem, thus my "*1" which could easily be "*-" if we prefer that). > Specifically, I like the use of angle brackets in Pod. Angle brackets > are simple, distinctive shapes; they remain wide in variable-width This is aesthetic preference. I could cite the reasons that I have an aesthetic preference for the other syntax, but the reality is that angle brackets aren't angle brackets; they are less-than (E<lt>) and greater- than signs (E<gt>). We ignore this fact at our peril, and the hacks in pod syntax (e.g. C<< < >>) to get around this are glaring anti- huffmanisms. > The most common use of them in Perl 5--method call/dereference--is > going away in Perl 6 Hmm, I remain unconvinced of that as the most common use, especially with the copious use of =>. Still, in my local source tree you're right, though by < a factor of 2. Perl 6 also adds new uses of E<gt> and E<lt> for pipelining, and further expands the usefulness of the => operator as a pair constructor. Rules also add new uses of these characters, but those are balanced, so improving POD with a real grammar specification would solve for that. > Pod needs incremental improvements--tables Oops, forgot that one. I'll add it tonight, when I get home from work. > (maybe) footnotes Good point, and I'd add that to X[...] rather than introducing something new, personally. > simpler links, tweaks to =begin/=end, etc. I think everything you list above is EXACTLY AJS Kwid, with one exception, which is the dreaded paradigm shift of using [] instead of <> Much as it may be an EMOTIONAL sticking point, it's a very minor thing. If we can agree on everything else, and I suspect we can, then let's come back to that. > Pod does *not* need to be ripped > out and replaced with something very different, yes, yes, yes! > especially something > that involves adding "line noise" to documents intended for human > consumption. yes, yes, yes! Thanks Brent, I'm not sure if you intended your mail as an endorsement, but other than one sticking point, you and I appear to be on the same page. Thank you for your message.
