Re: Gripes about Pod6 (S26)
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
Re: Gripes about Pod6 (S26)
Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ My plan is to keep writing my own various docs in Pandoc Markdown (regardless of what programming language I'm working in at the moment), and if I *really* need POD5 or POD6, just use Pandoc to convert them to html, and then find a module on the CPAN to convert the resulting html to POD5 or POD6 (Pandoc doesn't currently convert directly to either Pod). I encourage others to do the same. It's funny; the Python folks left their previous doc format (LaTeX), and went (IMO) in the right direction, but ended up going with the less attractive [reST] rather than Markdown. [reST]: http://docutils.sourceforge.net/rst.html ---John
Re: Gripes about Pod6 (S26)
* John Gabriele (jmg3...@gmail.com) [100209 14:31]: [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ [reST]: http://docutils.sourceforge.net/rst.html Or, more Perl like: [OODoc] http://perl.overmeer.net/oodoc/ http://perl.overmeer.net/oodoc/html/jump.cgi?OODoc_Parser_Markov62 -- MarkOv Mark Overmeer MScMARKOV Solutions m...@overmeer.net soluti...@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
Re: Gripes about Pod6 (S26)
On Wed, Feb 10, 2010 at 8:50 AM, Mark Overmeer m...@overmeer.net wrote: * John Gabriele (jmg3...@gmail.com) [100209 14:31]: [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ [reST]: http://docutils.sourceforge.net/rst.html Or, more Perl like: [OODoc] http://perl.overmeer.net/oodoc/ http://perl.overmeer.net/oodoc/html/jump.cgi?OODoc_Parser_Markov62 It's interesting to me that language implementations very often have their own NIH doc markup formats. For example: * Perl 5: POD * Perl 6: Pod * Python: reST * Ruby: rdoc * PLT Scheme: Scribble * Java: Javadoc I think Haskell may have something that their Haddock program uses. Also, IIRC, C and C++ users often use doxygen (though I realize that tool can be use with other languages as well). I used to wonder why these languages just don't use some generally accepted generic standard, such as LaTeX, Texinfo, or Docbook, or maybe even the MoinMoin wiki syntax (which is fairly common among wikis). After having used almost all of those tools, what I found was that: * it's tiresome to have to re-learn each different format if going back to edit old docs (or other people's docs) * it's a bother to have to set up my editor for every different format (and syntax highlighting doesn't always work right) * I tended to always come back to the simplest (and prettiest) thing that worked (Pandoc's Markdown) * I often ended up looking at my docs in `less` instead of taking the time to convert them to some other format for better viewing * many forums and blogs already use Markdown, most people already know it, many often use it without even knowing it Also though, interesting aside: Parrot is already at v2.0.0. It supports many languages. It's possible that someone might want to contribute docs to more than one of its hosted language implementations, so, using a common doc format might be desirable. Parrot also is often thought of as being very Perl-centric. Having it's biggest most sophisticated project use a common simple doc format might help shed that perception. ---John
Re: Gripes about Pod6 (S26)
On Tue, Feb 9, 2010 at 9:31 AM, John Gabriele jmg3...@gmail.com wrote:
Personally, I've always thought that Perl has a very natural feel to
{snip}
Gah. Sorry for the quasi-double-post. I posted on google groups, it
didn't show up, then I jumped the gun and posted a similar message to
the ML.
---John
r29675 - in docs/Perl6/Spec: . S32-setting-library
Author: lwall Date: 2010-02-10 18:10:26 +0100 (Wed, 10 Feb 2010) New Revision: 29675 Modified: docs/Perl6/Spec/S03-operators.pod docs/Perl6/Spec/S09-data.pod docs/Perl6/Spec/S32-setting-library/Containers.pod Log: [Spec] squash [;] fossils noticed by eternaleye++ Modified: docs/Perl6/Spec/S03-operators.pod === --- docs/Perl6/Spec/S03-operators.pod 2010-02-10 11:20:25 UTC (rev 29674) +++ docs/Perl6/Spec/S03-operators.pod 2010-02-10 17:10:26 UTC (rev 29675) @@ -15,8 +15,8 @@ Created: 8 Mar 2004 -Last Modified: 5 Feb 2010 -Version: 190 +Last Modified: 10 Feb 2010 +Version: 191 =head1 Overview @@ -4149,10 +4149,6 @@ [1,2,3] # make new Array: 1,2,3 [,] 1,2,3 # same thing -You may also reduce using the semicolon second-dimension separator: - -[[;] 1,2,3] # equivalent to [1;2;3] - Builtin reduce operators return the following identity values: [**]() # 1 (arguably nonsensical) @@ -4733,13 +4729,6 @@ ... } -To read arrays serially rather than in parallel, use Clist(@x;@y). -This wins a useless use of list award in this case since you could -always just write C(@x,@y) to mean the same thing. But sometimes -it's nice to be explicit about that: - -@foo := [[1,2,3],[4,5,6]]; say list([;] @foo); # 1,2,3,4,5,6 - =head1 Minimal whitespace DWIMmery Whitespace is no longer allowed before the opening bracket of an array Modified: docs/Perl6/Spec/S09-data.pod === --- docs/Perl6/Spec/S09-data.pod2010-02-10 11:20:25 UTC (rev 29674) +++ docs/Perl6/Spec/S09-data.pod2010-02-10 17:10:26 UTC (rev 29675) @@ -13,8 +13,8 @@ Created: 13 Sep 2004 -Last Modified: 9 Feb 2010 -Version: 39 +Last Modified: 10 Feb 2010 +Version: 40 =head1 Overview @@ -842,10 +842,19 @@ @nums[0;1;2] -instead, then you need to use the C[;] reduction operator: +it is not good enough to use the C| prefix operator, because +that interpolates at the comma level, so: -@nums[[;] 0..2] +@nums[ |(0,1,2) ] +just means + +@nums[ 0,1,2 ]; + +Instead, to interpolate at the semicolon level, you need to use the C|| prefix operator: + +@nums[ ||(0..2) ] + The zero-dimensional slice: @x[] Modified: docs/Perl6/Spec/S32-setting-library/Containers.pod === --- docs/Perl6/Spec/S32-setting-library/Containers.pod 2010-02-10 11:20:25 UTC (rev 29674) +++ docs/Perl6/Spec/S32-setting-library/Containers.pod 2010-02-10 17:10:26 UTC (rev 29675) @@ -19,8 +19,8 @@ Created: 19 Feb 2009 extracted from S29-functions.pod -Last Modified: 2 Feb 2010 -Version: 15 +Last Modified: 10 Feb 2010 +Version: 16 The document is a draft. @@ -61,10 +61,13 @@ Typically, you could just write C(@a,@b,@c), but sometimes it's nice to be explicit about that: - @foo := [[1,2,3],[4,5,6]]; say cat([;] @foo); # 1,2,3,4,5,6 + @foo := [[1,2,3],[4,5,6]]; say cat(||@foo); # 1,2,3,4,5,6 In addition, a CCat in item context emulates the CStr interface lazily. +[Conjecture: Cats should maybe just do the lazy strings, and leave flattening +to other operators.] + =item roundrobin our Parcel multi roundrobin( *...@list )
Re: Gripes about Pod6 (S26)
John Gabriele wrote: Personally, I've always thought that Perl has a very natural feel to it, and deserves a doc markup format that's also natural: [Markdown] (and [Pandoc]'s Markdown has just the right additions, IMO). [Markdown]: http://daringfireball.net/projects/markdown/ [Pandoc]: http://johnmacfarlane.net/pandoc/ I definitely prefer Markdown's approach to inline markup over POD's approach: e.g., _italic_ strikes me as much more legible than Iitalic. That said, Markdown doesn't go far enough in this regard, even with the Pandoc revisions: for instance, there's nothing equivalent to C or R in Markdown. I'm very much in favor of revising Perl 6's documentation system to more closely resemble Markdown; but I'd strongly recommend going through the list of Pod 6 inline tags and seeing how much of that can be reasonably implemented in a Markdown-like fashion. And Markdown gives you nothing in terms of determining how to go about embedding documentation within a code file: for that, you'd still need something along the lines of Pod 6's =begin/=end, =for, and even #=. That said, if a Markdown-like syntax were to get implemented, it might be possible to do away with documentation-specific delimiters, relying instead on the standard comments. I have more thoughts on this; but they'll have to wait for a bit. -- Jonathan Dataweaver Lang
Re: Gripes about Pod6 (S26)
Carl observed: 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. 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. The latter is entirely true but, fortunately, also very easily remedied. I hereby disclaim all present and future ownership of S26. :-) By all means put the latest update on the repo (or maybe remove S26 entirely), and start redesigning it collaboratively. Please note that I am not in any way upset, angry, petulant, or otherwise disaffected. I only want the very best for every aspect of Perl 6. If the experience of respected and active developers suggests that Pod 6 isn't a step in the right direction, I can only feel disappointed in myself, apologize for my failure, and gratefully turn the task over to those with better ideas and more time and energy to devote to the problem. As regards Pod vs Pandoc (which is pretty clearly the leading contender of the structured text notations), I do think Pod has some decided advantages. For example, I feel it's better to have four basic metasyntaxes (X, =IDENT, :OPTION, #=) and most with identifier-based labels, than to have over two dozen (plus embedded HTML and TeX) all with symbolic labels. I guess I feel that Pandoc/Markdown/ReST/etc. are optimized for writing documentation source, whereas Pod is optimized for reading documentation source. I'm not sorry I aimed for the latter, whatever the deficiencies in the result. Carl also suggested: 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. Outwardly this is self-evidently true. One need only look at the (lack of) commit log for S26. :-( Inwardly, something else entirely is happening. A design(er) can only respond effectively when subjected to a clear net force pushing or pulling in some well-defined direction. The redesign of Pod has been subject to an enormous number of such forces. Unfortunately they push and pull it in every possible mutually contradictory direction, thereby producing very little overall impetus. So I would encourage those of you who are going to collectively take over the shepherding of this synopsis to go back through the p6l archives and review the many many posts commenting on and requesting features for Perl 6 documentation. In particular, please look carefully at the very different needs of those who document OO code, procedural code, frameworks, modules, applications, design documents, presentations, and Perl itself. You will find that many of these contributors ignore, discount, or actively disparage the needs of their fellow users. For example, in this very thead: I'm not writing a book, I'm writing code. And if I was writing a book, I wouldn't be dumb enough to write it in POD. Yet what is the Perl documentation itself but a series of book chapters? And surely that documentation is the largest single use of Pod anywhere? Should we not write Perl's own documentation in Perl's own documentation notation? Should we really discourage the use of standard headings to consistently mark the common components of these (and most other) Perl-related documents? I sincerely hope that the future community of designers of Perl 6 's documentation format will find a way to honour and support the very different needs of *all* the creators and users of Perl, not just the needs of the most prominent, or the needs of the most experienced, or the needs of the most loquacious. I have always thought that was the *real* challenge of post-modern language design. Damian
Re: Gripes about Pod6 (S26)
On Fri, Feb 05, 2010 at 03:43:04PM -0500, Austin Hastings wrote: Second, POD is not XML, and it definitely isn't DOCBOOK. Why do I need magic reserved words like TOC and APPENDIX? I'm not writing a book, I'm writing code. And if I was writing a book, I wouldn't be dumb enough to write it in POD. Actually, it's worth noting that (a slightly modified version of) Perl 5 POD has indeed been used to write several substantial books. I'd be very sad if (Perl 6) POD couldn't be easily used or converted into something that can be used to generate manual pages and reference documentation. Pm
