Re: Gripes about Pod6 (S26)

2010-02-09 Thread John Gabriele 
Personally, I've always thought that Perl has a very natural and
well-worn feel to it, and deserves a doc markup format that also feels
natural. What works very well for me is [Markdown] (and [Pandoc]'s
Markdown has mostly just the right additions, IMO).

[Markdown]: http://daringfireball.net/projects/markdown/
[Pandoc]: http://johnmacfarlane.net/pandoc/

(Note: Pandoc is written in Haskell. For anyone who's interested, I
put up some quick notes on installing Haskell + Pandoc specifically
onto Ubuntu 9.04 at
.)

My own plan is to keep writing my docs in Pandoc Markdown (regardless
of what language I'm working in at the moment), and if I *really* need
POD or Pod, I'll just use Pandoc to convert them to some intermediate
format, and then find a module on the CPAN to convert *that* to POD or
Pod. I encourage others to do the same.

Further, for API-style docs, I've been experimenting with extracting
specifically-marked markdown-formatted code comments and then passing
them through pandoc. For example, maybe something like this:

#>>>
# forage
# --
#
# This function will hunt around for any
# nuts that may or may not be present on
# the system.
#
# *Warning:* Not compatible with most
# squirrel-related modules.
#
# Args:
#
#   * search-radius: default is 5 meters
#   * default behaviour if confronted by cat ...
#
#<<<
sub forage {
# ...
}

It's funny; the Python folks left their previous doc format (LaTeX),
and went in the right direction (IMO), but ended up going with the
less attractive [reST], rather than Markdown.

[reST]: http://docutils.sourceforge.net/rst.html

---John

r29671 - docs/Perl6/Spec

2010-02-09 Thread pugs-commits 
Author: lwall
Date: 2010-02-10 06:35:20 +0100 (Wed, 10 Feb 2010)
New Revision: 29671

Modified:
   docs/Perl6/Spec/S06-routines.pod
   docs/Perl6/Spec/S09-data.pod
Log:
[S06,S09] change **() special form to prefix:<||> by analogy to prefix:<|>


Modified: docs/Perl6/Spec/S06-routines.pod
===
--- docs/Perl6/Spec/S06-routines.pod2010-02-10 04:04:09 UTC (rev 29670)
+++ docs/Perl6/Spec/S06-routines.pod2010-02-10 05:35:20 UTC (rev 29671)
@@ -16,8 +16,8 @@
 
 Created: 21 Mar 2003
 
-Last Modified: 2 Feb 2010
-Version: 127
+Last Modified: 9 Feb 2010
+Version: 128
 
 This document summarizes Apocalypse 6, which covers subroutines and the
 new type system.
@@ -1285,17 +1285,14 @@
 for $tmp.zip.slice -> [$i, $a] { say "$i: $a" }
 
 Conjectural: To interpolate a feed into a subscript such that the
-slice turns into multiple subscripts, you need target the special form
-C<**()>, since targeting a bare C<@(*)> would merely interpolate into
-the current slice element's list.  The C<**()> form may be used only
-where a semicolon would be appropriate.  If no expression is supplied
-in the parentheses, $(*) is assumed as the current incoming feed.
-These are equivalent:
+slice turns into multiple subscripts, you need to use C<< prefix:<||> >>,
+which works just like prefix:<|> except that it interpolates at the slice
+level rather than the flat list level:
 
 (0..10; 0..10).zip
 zip(0..10; 0..10)
-(0..10; 0..10) ==> zip( **() )
-(0..10; 0..10) ==> $feed; zip( **($feed) )
+(0..10; 0..10) ==> zip( ||@(*) )
+(0..10; 0..10) ==> $feed; zip( ||$feed )
 
 Usually it's better to just use the method form.
 

Modified: docs/Perl6/Spec/S09-data.pod
===
--- docs/Perl6/Spec/S09-data.pod2010-02-10 04:04:09 UTC (rev 29670)
+++ docs/Perl6/Spec/S09-data.pod2010-02-10 05:35:20 UTC (rev 29671)
@@ -13,8 +13,8 @@
 
 Created: 13 Sep 2004
 
-Last Modified: 2 Feb 2010
-Version: 38
+Last Modified: 9 Feb 2010
+Version: 39
 
 =head1 Overview
 
@@ -358,9 +358,10 @@
 You can pass a slice (of any dimensionality) for the shape as well:
 
 @shape = 4, 2;
-my int @ints[ **(@shape) ];
+my int @ints[ ||@shape ];
 
-The **() form interpolates a list into a semicolon list.
+The C<< prefix:<||> >> operator interpolates a list into a semicolon list at
+the semicolon level.
 
 The shape in the declaration merely specifies how the array will
 autovivify on first use, but ends up as an attribute of the actual
@@ -399,9 +400,9 @@
 @array.postcircumfix:<[ ]>( ((@x,@y)) );
 
 To interpolate an array at the semicolon level rather than the comma level,
-use the special C<**()> form:
+use the C<< prefix:<||> >> operator:
 
-@array[**(@x)]
+@array[||@x]
 
 which is equivalent to
 
@@ -430,16 +431,16 @@
 my @spacetime[*;*;*;**];   # Three or more dimensions
 my @coordinates[100;100;100;**];   # Three or more dimensions
 
-Note that C<**> is a shorthand for something that means C<**(* xx *)>, so the 
extra
+Note that C<**> is a shorthand for something that means C<||(* xx *)>, so the 
extra
 dimensions are all of arbitrary size. To specify an arbitrary number
 of fixed-size dimensions, write:
 
-my @coordinates[ **(100 xx *) ];
+my @coordinates[ ||(100 xx *) ];
 
 This syntax is also convenient if you need to define a large number of
 consistently sized dimensions:
 
-my @string_theory[ **(100 xx 11) ];# 11-dimensional
+my @string_theory[ ||(100 xx 11) ];# 11-dimensional
 
 =head1 User-defined array indexing
 
@@ -718,7 +719,7 @@
 
 An array C<@array> can be tied to a PDL at declaration time:
 
-my num @array[**(@mytensorshape)] is PDL;
+my num @array[||@mytensorshape] is PDL;
 my @array is PDL(:shape(2;2;2;2)) of int8;
 
 PDLs are allowed to assume a type of C by default rather than
@@ -1101,11 +1102,11 @@
 autothread.
 
 If you use an unbound array parameter as a semicolon-list interpolator
-(via the C<**()> operator), it functions as a wildcard list of
+(via the C<< prefix:<||> >> operator), it functions as a wildcard list of
 subscripts that must match the same everywhere that parameter is used.
 For example,
 
-do -> @wild { @b[**(reverse @wild)] = @a[**(@wild)] };
+do -> @wild { @b[ ||@wild.reverse ] = @a[ ||@wild ] };
 
 produces an array with the dimensions reversed regardless of the
 dimensionality of C<@a>.

r29673 - docs/Perl6/Spec

2010-02-09 Thread pugs-commits 
Author: lwall
Date: 2010-02-10 06:51:10 +0100 (Wed, 10 Feb 2010)
New Revision: 29673

Modified:
   docs/Perl6/Spec/S03-operators.pod
Log:
[S03] add description of prefix:<||> semantics


Modified: docs/Perl6/Spec/S03-operators.pod
===
--- docs/Perl6/Spec/S03-operators.pod   2010-02-10 05:40:15 UTC (rev 29672)
+++ docs/Perl6/Spec/S03-operators.pod   2010-02-10 05:51:10 UTC (rev 29673)
@@ -35,7 +35,7 @@
 L  Method postfix.meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .:
 N  Autoincrement ++ --
 R  Exponentiation**
-L  Symbolic unary! + - ~ ? | +^ ~^ ?^ ^
+L  Symbolic unary! + - ~ ? | || +^ ~^ ?^ ^
 L  Multiplicative* / % +& +< +> ~& ~< ~> ?& div mod
 L  Additive  + - +| +^ ~| ~^ ?| ?^
 L  Replication   x xx
@@ -650,6 +650,19 @@
 
 =item *
 
+C<< prefix:<||> >>, flatten object into semicolon list
+
+|| $parcel
+
+Interpolates the elements of the C (or any other ordered value)
+into the current argument list as if they had been specified literally,
+separated by semicolons, that is, at the multi-dimensional level.
+It is an error to use this operator outside of a slice context; in
+other words it must be bound into a C<**> (slice) parameter rather
+than a C<*> (slurpy) parameter.
+
+=item *
+
 C<< prefix:<+^> >>, numeric bitwise negation
 
 +^$x