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:


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

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.


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

Reply via email to