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
