Austin (>): > I've been doing a bunch of NQP and PIR coding, where Pmichaud++ has been > trying to support some kind of POD syntax. With the release of the S26 > draft, he has tightened the parsing to follow more of the rules laid out in > the spec, and after a few months, I've noticed that the trend (for > not-quite-pod) is definitely getting worse. POD 6 isn't very nice. It > certainly isn't an improvement on POD 5. > > To be clear, by "not an improvement on POD5" what I mean is "I have > abandoned POD6 in favor of block comments."
I read your email and thought "wow, this is very much like an email thread I hoped to start on p6l". > [...] Far > better to write #={ despite how ridiculous that is to type, than to consider > using """ (or better yet ''' which isn't shifted). Having used the #={ syntax consistently through one of my projects (Druid), I can only agree wholeheartedly. Look: <http://github.com/masak/druid/blob/2c02e2a26a5fff6ec1d2f47b2c28d7ad2435e359/lib/Druid/Game.pm> It was an interesting thing to try, and I'd love if doing it like that would somehow produce an HTML file à la JavaDoc, but right now there's only disadvantages to writing doc-comments like that: it looks jarring, both from the combination of of characters -- a complaint I don't normally have in Perl -- and the syntax highlighter (in vim as well as on Github) goes haywire. I can look at the comment syntax in other languages and say that they "fit in" with the rest of the language. I cannot say that about #={} in Perl 6. Taking a step back, I think that S26 suffers from being at a stage where much of the rest of the specification was in about 2005. It contains a lot of good ideas, but also many rough edges stemming from non-obvious corner cases and things that simply don't work in practice. It's in need of a bit of a killing of darlings. Partly that is because documentation isn't at the forefront of things that need to be implemented for Perl 6 to be useful, so it's kind of lagging behind the rest. (The same situation can be seen with S17-concurrency, S19-commandline and S22-package-format, to name a few.) Partly it's because Damian is the "owner" of that synopsis, and he practices a kind of "drive-by-updating" to it. As a case in point of this latter effect, the extensive changes made by Damian in August *still* haven't hit the Pugs repo. <http://www.nntp.perl.org/group/perl.perl6.language/2009/08/msg32352.html> <http://perlcabal.org/syn/S26.html> As a consequence, whereas many of the other synopses are happily ticking along, getting small improvements on a daily basis, S26 just sits there in a kind of limbo. It doesn't get one bit of feedback from the things people learn from actually using it. That's just a pity. Austin, many of the rest of your point went above my head, either because I don't have the same knowledge about other documentation formats as you do, or because I don't share the exact same practical experience in writing Pod 6. But I think that the future of S26 is very much dependent on whether it'll be able to respond to the needs of Perl 6 developers. Right now it doesn't respond to much of anything. I hope that changes. // Carl