Re: S26 - The Next Generation
Aaron Sherman asked: Should there be an explicit way to step this down to just parsing the bits that are called out as pod? The original conception allowed for Pod to be independent of the interleaved language. That has now been supplanted by a model that views Pod as an integral part of Perl. There's definitely a trade-off there, but one we've decided to make. So, no, there are no longer any plans to extend Pod to documenting *everything*, except so far as Perl 6 will be ale to subsume everything (in line with Larry's musings of braided languages). There is no explicit mention in the document as to what happens at the Perl level when the closing bracket is reached at a point that is not the end of a line (i.e. it is not followed by whitespace that contains a newline character). Here's an example: my $a #-[stop the presses!] = 4; Except for the #~ instead of #=, that's valid (and documented) Perl 6. That is, Pod comments work exactly like non-Pod comments. As Synopsis 26 now states: That is, declarator Pod blocks are syntactically like ordinary Perl 6 single-line comments and embedded comments. * This new declarator block form is special. During source code parsing, normal Pod blocks are simply appended into an array attribute of surrounding Comment object in the AST (which is just $=POD, at the top level). However declarator blocks are *also* appended to the .WHY attribute of the declarator at the start of the most recent (or immediately following) line. I'd very much like to establish that at default optimization levels for execution, this information is not guaranteed to be maintained past the creation of the AST. Unfortunately, it is. Perl 6 defines that Perl 6 programs can always access their own Pod at runtime (via $=POD). You probably can't even optimize the information away in the absence of any compile-time reference to $=POD, since there are plenty of symbolic ways to refer to $=POD at run-time. Damian
Re: S26 - The Next Generation
On Thu, Sep 17, 2009 at 1:05 AM, Damian Conway dam...@conway.org wrote: Aaron Sherman asked: ... I'd very much like to establish that at default optimization levels for execution, this information is not guaranteed to be maintained past the creation of the AST. Unfortunately, it is. Perl 6 defines that Perl 6 programs can always access their own Pod at runtime (via $=POD). You probably can't even optimize the information away in the absence of any compile-time reference to $=POD, since there are plenty of symbolic ways to refer to $=POD at run-time. Can some concept/implementation of $=POD lazyness only incur the memory and performance hit on access? -y
Re: S26 - The Next Generation
On Thu, 2009-09-17 at 11:12 -0700, yary wrote: On Thu, Sep 17, 2009 at 1:05 AM, Damian Conway dam...@conway.org wrote: Aaron Sherman asked: ... I'd very much like to establish that at default optimization levels for execution, this information is not guaranteed to be maintained past the creation of the AST. Unfortunately, it is. Perl 6 defines that Perl 6 programs can always access their own Pod at runtime (via $=POD). You probably can't even optimize the information away in the absence of any compile-time reference to $=POD, since there are plenty of symbolic ways to refer to $=POD at run-time. Can some concept/implementation of $=POD lazyness only incur the memory and performance hit on access? Alternately it should be possible to declare that the Pod data be dropped before mainline runtime begins. For example, it ought to be possible for a compiling implementation such as Rakudo to declare that the Pod data not be frozen into the PBC file. (If this is already specced, I apologize -- I haven't searched for it.) -'f
Re: S26 - The Next Generation
yary asked: Can some concept/implementation of $=POD lazyness only incur the memory and performance hit on access? IANAImplementor, but I suspect that virtually all of the performance hit could be incurred at run-time, if it happened to be implemented that way. The memory hit too, if necessary, but that would then make the performance hit hit very hard indeed. I suspect that it would be better to preserve the Poddish parts of the AST structure and just have them transmogrify into the appropriate Pod objects on demand. Damian
Re: S26 - The Next Generation
Not actually S26; but closely related: should $=POD and .WHY be read-only? Also, should there be other Pod variables besides $=POD? If so, which ones? Back on the subject of S26: should declarator blocks and aliases be able to introspect the object with which they're associated? That is, should you be able to say things like A.WHAT or A.^methods? (If so, be sure never to say A.WHY.) -- Jonathan Dataweaver Lang
Re: S26 - The Next Generation
I'm jumping in on an old conversation because I only just had time to catch
up last night. I have a few questions that I think are probably still
pertinent.
On Sun, Aug 16, 2009 at 4:26 PM, Damian Conway dam...@conway.org wrote:
Executive summary:
* Pod is now just a set of specialized forms of Perl 6 comment
* Hence it must always parsed using full Perl 6 grammar: perl6 -doc
This one seems relatively obvious, so it's probably been proposed. I skimmed
a few of the responses and didn't see it, but that means little, I'm sure.
This makes me wonder about other languages. I've been known to use POD in
strings within other languages that lack a facility for documenting a
program as a facility rather than as a collection of elements (which is the
javadoc et al. trap).
Should there be an explicit way to step this down to just parsing the bits
that are called out as pod? For example:
#!/bin/sh
#=notperl :leading# :trailing\n
cd $1
#=head1 ...
# ...
#=cut
Obviously causing leading #s to be stripped when evaluating the podishness
of a section of the program, up to the next newline. Similarly a CDATA block
in XML might specify (on its own line) #=notperl :langxml :leading !--
and :trailing -- as the begin and end tokens of potentially valid
POD sections. The evaluation of each identified section then being gated on
the presence of a following = token. I can't think of a language that can't
support POD in this way, but I'm sure someone will provide an example ;)
Actually, in retrospect vanilla C89 might be problematic. I seem to remember
that C9X introduces // so it could pull this off. I can imagine a messy
solution in C using #define, but it would produce compile-time warnings in
some compilers.
Interestingly, this would have the side-benefit of making any program in any
language into valid Perl code, given the appropriate notation at the start
of the program... Kind of nifty if not strictly a practical benefit.
[...]
* In addition to delimited, paragraphed, and abbreviated Pod blocks,
documentation can now be specified in a fourth form:
my $declared_thing; #= Pod here until end of line
sub declared_thing () { #=[ Pod here
until matching
closing bracket
]
...
}
There is no explicit mention in the document as to what happens at the Perl
level when the closing bracket is reached at a point that is not the end of
a line (i.e. it is not followed by whitespace that contains a newline
character). Here's an example:
my $a #-[stop the presses!] = 4;
I'm not sure that I even think this is a good idea (nor a bad one, for that
matter), but the documentation does not make this clear. It seems likely
that the expected behavior is for Perl to treat the # as the start of a
comment, even though it encounters parsable pod thereafter, and to continue
to process the remaining part of the line as a comment, however this brings
multi-line bracketted POD into question:
sub fly($like, $to, $spirit) #=[
time keeps on slippin'
] { # error - this brace is not considered code?
...
}
fly(:like('eagle'), :to('sea'), :spirit('carry me'))
* This new declarator block form is special. During source code parsing,
normal Pod blocks are simply appended into an array attribute of
surrounding Comment object in the AST (which is just $=POD, at the
top level). However declarator blocks are *also* appended to the
.WHY attribute of the declarator at the start of the most recent
(or immediately following) line.
I'd very much like to establish that at default optimization levels for
execution, this information is not guaranteed to be maintained past the
creation of the AST. This allows optimizations which might place declared
elements into types which cannot maintain additional data (e.g. a Parrot
I-register). Perhaps in some cases we would want to provide such guarantees.
I wouldn't be opposed to an explicit way to request such a guarantee. For
example:
sub junk($things) is documented
#= junk happens
{ ... }
Now, even if junk is inlined and optimized away, we guarantee that its
documentation will continue to be stored in some way that can be retrieved.
This might even prevent certain classes of optimizations, but that's
implementation specific.
* Hence, they can be used to document code directly, which
documentation can then be pulled out by introspecting either
$=POD or the declarators themselves. Documented declarators
look like this:
Although it's something that could be added on after-the-fact, I think it's
worth calling for this up-front: All of your comments about .WHY seem to
indicate that it behaves recursively, walking the tree and pulling out any
documentation for child nodes. That's fine, but there really should be a
user-accessible and well defined way to limit that
Re: S26 - The Next Generation
Jon Lang wrote: An unrelated possibility would be to allow empty A tags in a declarator block, with 'A' being replaced with the name of the declarator to which the block is attached: And then I think: A_ -- Ruud (indoctrinated)
Re: S26 - The Next Generation
Jon Lang elaborated:
I don't think that there will be a problem. First, #= is easy enough
to distinguish from #=; I don't foresee any confusion.
I'm not so sure. #= is a lot more like #= that =alias is. And the one
character of difference is on the non-significant (right-hand) side.
Need to think about it and role-play it a little.
With the ability to attach multiple declarator blocks to a single
declarator, it should be trivial to replace any one of them with a
declarator alias:
#=
class Foo {
#= Class Foo
#= a sample class used to illustrate.
#= This particular class has nothing in it.
}
See that's precisely my problem. I don't think the #= stands out at all
there as being an alias.
#= Class Aclass
class Foo {
#= a sample class used to illustrate.
#= This particular class has nothing in it.
#= Xthis assigns to the 'class' declarator alias.
And this illustrates my other qualm, that the two forms are just too similar.
And, yes, having the aliasing mechanism be something postfix(able) creates
issues of when the aliases come into existence.
I tend to agree. I only proposed numbering as a way of being able to
access different declarators without having to explicitly label them.
I can definitely understand if this option gets dropped as being too
error-prone with regard to maintenance.
That's my plan.
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias open
my Bool method open ($filename) {...}
=alias close
my Bool method close() {...}
=for para
Note that the Aopen method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute, while the Aclose
method closes that handle.
}
The problem with this example is that '=alias name' isn't a declarator
alias; it's a block alias.
I'm proposing to change that and allow explicit names on declarator
aliases as well.
Or, rather, to unify the two into a block-or-declarator alias.
my Bool method open ($filename) {...} #=[m1] #= Here's a
block for Am1.
my Bool method close () {...} #=m2
And given that brief names are going to be preferred, this could
result in very compact, yet still readable, combinations of declarator
aliases and blocks.
Yes, this is a definite advantage of the proposal. No question.
But I'm still concerned that the two syntaxes are just so similar.
I'll continue pondering the trade-off.
Damian
Re: S26 - The Next Generation
Jon Lang huh'd: Huh. Would you be able to do something like: =begin pod Welcome to $?FILE. ...and have it interpolate the file's name? Or would you need some special markup for this, such as: =begin pod Welcome to A$?FILE. The latter. Variables are just too common in documentation to have (some of) them interpolate automagically. Or would you have to alias the variable and then refer to it? No. I envisage that A would recognize an alias starting with a sigil, and auto-alias it for you. Damian
Re: S26 - The Next Generation
Raiph elucidated:
Hmm. I was thinking Pod would be parsed by a P6/PGE grammar, one that
could be relatively easily edited/extended to suit another context, because,
I thought, it could then be made available as a stock --doc subsystem that
all PCT based languages get more or less for free.
Sure, that might be possible. The problem is one of syntax. Pod, as currently
specified, defines two syntaxes for magic comments that define documentation.
The difficulty is that both those syntaxes might already be in use in
other languages (the /^ \h* \= ident/ syntax most certainly will be),
so you end up having to change the Pod parsing syntax on a per-language
basis. I can't really see that being very attractive to the implementors
of other languages, nor the inconsistency being very attractive to users
of those languages.
We need a way of referring to ambient code within Pod, without the
Podder having to write more code to get it.
I was thinking it would be possible to reference (compiler) variables
representing eg. the name and sig of a block being parsed, or a block
or declaration which has just been parsed, or which is just about to be
parsed, and that simply referencing these variables would be ok and
would save the need to create explicit named anchors.
Well, that certainly *is* possible in Pod, which will definitely have
access to any compile-time
Perl variables, including the following usually bits of information:
$?FILE Which file am I in?
$?LINE Which line am I at?
?ROUTINE Which routine am I in?
?BLOCK Which block am I in?
$?SCOPE Which lexical scope am I in?
$?PACKAGE Which package am I in?
$?MODULEWhich module am I in?
$?CLASS Which class am I in? (as variable)
$?ROLE Which role am I in? (as variable)
$?GRAMMAR Which grammar am I in?
But that's not necessarily enough. I can imagine many other pieces of code that
you might want both in the source and in the documentation, but which it would
not be easy to extract from the introspective variables. For example:
PRE
=alias precondition
{
$_ 0
}
or:
if ($?TESTING)
=alias example1
{
my $tree = TreeClass.new();
$tree.size() == 0 :okTrees start life empty;
$tree.insert(node value);
$tree.size() == 1 :okInsertion increases tree size;
}
Not to mention all of the clever uses I can't think of yet. ;-)
Damian
Re: S26 - The Next Generation
Jon Lang kept his promise:
I promised some further thoughts; here they are:
Much appreciated.
As written, declarator aliasing attaches the alias to a piece of code,
and draws both the name and the alias from that. What about using a
special case of the declarator block for this? That is:
class Database::Handle { #=alias
has IO $!handle; #=alias
my Bool method open ($filename) {...} #=alias
=for para
Note that the Amethod method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute.
}
or:
class Database::Handle { #=
has IO $!handle; #=
my Bool method open ($filename) {...} #=
=for para
Note that the Amethod method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute.
}
Definitely interesting ideas, especially the second one. My concern
would be that they compete
with the #= blocks which might also be needed on such declarations.
Regardless of what syntax you use for declarator aliasing, I'd also
recommend some sort of numbering scheme if you alias more than one
declarator of the same type in the same lexical scope:
It's definitely an issue I hadn't considered properly. However, I
think the correct
solution is not numbering (which is always fraught with problems when subsequent
maintenance adds an extra declarator in the middle), but rather naming. Like so:
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias open
my Bool method open ($filename) {...}
=alias close
my Bool method close() {...}
=for para
Note that the Aopen method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute, while the Aclose
method closes that handle.
}
I know this looks redundant. But the whole point of logical names is you
don't have to change them when the physical name changes:
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias open
my Bool method open_file ($filename) {...}
=alias close
my Bool method close_and_sync() {...}
=for para
Note that the Aopen method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute, while the Aclose
method closes that handle.
}
If you adopt the declarator block basis for declarator aliasing, you
could even let the documenter choose his own names:
class Database::Handle { #=
has IO $!handle; #=
my Bool method open ($filename) {...} #=m1
my Bool method close () {...} #=m2
An unrelated possibility would be to allow empty A tags in a
declarator block, with 'A' being replaced with the name of the
declarator to which the block is attached:
These are both very useful ideas.
I'll ponder them carefully in preparation for the next revision.
Thanks, Jon!
Damian
Re: S26 - The Next Generation
Damian Conway wrote: Raiph elucidated: I was thinking it would be possible to reference (compiler) variables representing eg. the name and sig of a block being parsed, or a block or declaration which has just been parsed, or which is just about to be parsed, and that simply referencing these variables would be ok and would save the need to create explicit named anchors. Well, that certainly *is* possible in Pod, which will definitely have access to any compile-time Perl variables, including the following usually bits of information: $?FILE Which file am I in? $?LINE Which line am I at? ?ROUTINE Which routine am I in? ?BLOCK Which block am I in? $?SCOPE Which lexical scope am I in? $?PACKAGE Which package am I in? $?MODULE Which module am I in? $?CLASS Which class am I in? (as variable) $?ROLE Which role am I in? (as variable) $?GRAMMAR Which grammar am I in? Huh. Would you be able to do something like: =begin pod Welcome to $?FILE. ...and have it interpolate the file's name? Or would you need some special markup for this, such as: =begin pod Welcome to A$?FILE. Or would you have to alias the variable and then refer to it? -- Jonathan Dataweaver Lang
Re: S26 - The Next Generation
Damian Conway wrote:
Jon Lang kept his promise:
I promised some further thoughts; here they are:
Much appreciated.
You're welcome.
As written, declarator aliasing attaches the alias to a piece of code,
and draws both the name and the alias from that. What about using a
special case of the declarator block for this? That is:
class Database::Handle { #=alias
has IO $!handle; #=alias
my Bool method open ($filename) {...} #=alias
=for para
Note that the Amethod method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute.
}
or:
class Database::Handle { #=
has IO $!handle; #=
my Bool method open ($filename) {...} #=
=for para
Note that the Amethod method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute.
}
Definitely interesting ideas, especially the second one. My concern
would be that they compete
with the #= blocks which might also be needed on such declarations.
I don't think that there will be a problem. First, #= is easy enough
to distinguish from #=; I don't foresee any confusion. Second, your
existing rules for #= already allow for multiple such blocks to be
attached to one thing, with the rule being that you append the latter
ones to the former ones:
#= Class Foo
class Foo {
#= a sample class used to illustrate.
#= This particular class has nothing in it.
}
...results in the equivalent of:
=for pod
Class Foo
a sample class used to illustrate.
This particular class has nothing in it.
With the ability to attach multiple declarator blocks to a single
declarator, it should be trivial to replace any one of them with a
declarator alias:
#=
class Foo {
#= Class Foo
#= a sample class used to illustrate.
#= This particular class has nothing in it.
}
There _is_ a question about when the alias becomes available:
#= Class Aclass
class Foo {
#= a sample class used to illustrate.
#= This particular class has nothing in it.
#= Xthis assigns to the 'class' declarator alias.
Would Aclass in the first line become 'Foo', or would it be whatever
Aclass was before that line? My later suggestion of an empty A
mitigates this problem by making such references less frequent in
practice; but it doesn't eliminate it. My personal preference would
be for it to refer to 'Foo'; but that would involve postponing the
evaluation of Foo's WHY block until all possible relevant data has
been collected.
Regardless of what syntax you use for declarator aliasing, I'd also
recommend some sort of numbering scheme if you alias more than one
declarator of the same type in the same lexical scope:
It's definitely an issue I hadn't considered properly. However, I
think the correct
solution is not numbering (which is always fraught with problems when
subsequent
maintenance adds an extra declarator in the middle), but rather naming. Like
so:
I tend to agree. I only proposed numbering as a way of being able to
access different declarators without having to explicitly label them.
I can definitely understand if this option gets dropped as being too
error-prone with regard to maintenance.
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias open
my Bool method open ($filename) {...}
=alias close
my Bool method close() {...}
=for para
Note that the Aopen method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute, while the Aclose
method closes that handle.
}
The problem with this example is that '=alias name' isn't a declarator
alias; it's a block alias. (I don't have a problem with the
underlying concept that you're trying to illustrate.) So Aopen
would be 'my Bool method open($filename) {...}', when what you'd be
looking for in a named declarator alias would be 'open'. (And it
might not even be that, unless you loosen the syntactic requirements
for a block alias: there are no subsequent curly braces to define how
much gets aliased.) Which brings me to:
If you adopt the declarator block basis for declarator aliasing, you
could even let the documenter choose his own names:
class Database::Handle { #=
has IO $!handle; #=
my Bool method open ($filename) {...} #=m1
my Bool method close () {...} #=m2
This would be a way to do a named declarator alias, for distinguishing
between multiple aliases to the same type of declarator.
Indeed, you might end up making extensive use of embedded named
declarator aliases (ENDAs? :P ), since as soon as you reach the
close-bracket, you have the rest of the line available for other uses
(such as declarator blocks):
class Database::Handle
Re: S26 - The Next Generation
Damian: While I'm all in favour of other languages using Pod as a documentation format, I think that's unlikely. Pod says that anything of the form: =identfiier *anywhere* as the first non-whitespace of a line, is considered a Pod directive. I can't see many other language designers being willing to limit their assignment statements that way. Hmm. I was thinking Pod would be parsed by a P6/PGE grammar, one that could be relatively easily edited/extended to suit another context, because, I thought, it could then be made available as a stock --doc subsystem that all PCT based languages get more or less for free. Having to use aliases at all to refer to things that the Perl 6 compiler already has a name for seems like an ugly/heavyweight/suboptimal approach. I think aliases are essential. Ok. We need a way of referring to ambient code within Pod, without the Podder having to write more code to get it. I was thinking it would be possible to reference (compiler) variables representing eg. the name and sig of a block being parsed, or a block or declaration which has just been parsed, or which is just about to be parsed, and that simply referencing these variables would be ok and would save the need to create explicit named anchors. -- love, raiph
Re: S26 - The Next Generation
Smylers pointed out: * Hence it must always parsed using full Perl 6 grammar: perl6 -doc Having a multi-character option preceded by a single hyphen doesn't play well with bundling of single-character options... You make many good points. Changed to: perl --doc Thanks, Damian
Re: S26 - The Next Generation
I promised some further thoughts; here they are:
As written, declarator aliasing attaches the alias to a piece of code,
and draws both the name and the alias from that. What about using a
special case of the declarator block for this? That is:
class Database::Handle { #=alias
has IO $!handle; #=alias
my Bool method open ($filename) {...} #=alias
=for para
Note that the Amethod method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute.
}
The rules for what gets aliased would be the same as the rules for
what gets annotated. This is more compact than the =alias directive
sans arguments approach, as you can put the alias on the same line as
the declarator to which it is bound.
The downside is that it runs opposite to what declarator blocks
usually do: instead of attaching some Pod to the ambient code, it
attaches a piece of the ambient code to Pod. That, and alias is
appearing in the declarator block where the Pod parser would be
expecting content. Perhaps you could use some other symbol to
distinguish a declarator alias from a declarator block: e.g., #=
represents a declarator alias, while #= represents a declarator block.
So:
class Database::Handle { #=
has IO $!handle; #=
my Bool method open ($filename) {...} #=
=for para
Note that the Amethod method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute.
}
Regardless of what syntax you use for declarator aliasing, I'd also
recommend some sort of numbering scheme if you alias more than one
declarator of the same type in the same lexical scope:
=alias
class Database::Handle {
=alias
has IO $!handle;
=alias
my Bool method open ($filename) {...}
=alias
my Bool method close() {...}
=for para
Note that the Amethod1 method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute, while the Amethod2
method closes that handle.
}
If you adopt the declarator block basis for declarator aliasing, you
could even let the documenter choose his own names:
class Database::Handle { #=
has IO $!handle; #=
my Bool method open ($filename) {...} #=m1
my Bool method close () {...} #=m2
=for para
Note that the Am1 method of class Aclass
stores the resulting low-level database handle
in its private Ahas attribute, while the Am2
method closes that handle.
}
This would be more robust, in that you could rearrange the components
of the block without getting the aliases mixed up. It might even be
worthwhile to make the names mandatory.
You might even allow a second parameter which could (for example) be
used to engage in introspection of the attached thing, thus allowing
you to alias aspects of it other than its name. But I'd consider this
to be part of the Pod extensibility, rather than a core feature. An
example:
my Bool method open ($filename) {...} #=m1
#=m1-type Type
=para Am1 is a Am1-type.
Result:
Copen is a Cmethod.
--
An unrelated possibility would be to allow empty A tags in a
declarator block, with 'A' being replaced with the name of the
declarator to which the block is attached:
class Database::Handle { #=[the A class handles a database.]
has IO $!handle; #=[the A attribute identifies the database
to be handled.]
my Bool method open ($filename) {...} #=[the A method opens
the database.]
}
This would attach the CDatabase::Handle class handles the
database. to class Database::Handle, the C$!handle attribute
identifies the database to be handled. to $!handle, and the Copen
method opens the database. to method open.
--
Jonathan Dataweaver Lang
Re: S26 - The Next Generation
Damian Conway writes: It's Sunday evening and, as promised, here's the new draft of S26. Wow, thanks for that -- it's most impressive and I'm already excited about what it will allow and how it permits improved documentation. * Hence it must always parsed using full Perl 6 grammar: perl6 -doc Having a multi-character option preceded by a single hyphen doesn't play well with bundling of single-character options (such as perl -wle in Perl 5): * The above looks like a bundled version of -d -o -c. That some of those don't exist doesn't affect that impression: it isn't reasonable to expect a user to know all options before she uses any of them, so if she's seen some single-letter options but doesn't know about -doc then she will misinterpret -doc. * In order for -doc to work, 'long' options have to trump 'bundled' options with the same spelling. If a version of Perl 6 introduces all of the -d, -o, and -c options then -cdo, -cod, -ocd, and so on will all be synonyms but -doc will be completely different. Putting arbitrary restrictions on bundling order that aren't related to the options themselves is an irritating cognitive load: if you're adding the -c option to a program that already has -do it matters where you put the c. * If long options with single hyphens are permitted in general then a future version of Perl 6 may add new ones. That means that _no_ single-character option bundling is safe to use from a forwards compatibility viewpoint, because any sequence may become a long option -- and hence radically change semantics -- in future. Using double-hyphens for all long options disambiguates them from bundled short options, and is familiar to many users from other software which follows that convention. Indeed others (including S19) already seem to believe that two hyphens are needed: jerry gay writes: this is why it's spelled 'perl6 --doc' Smylers
Re: S26 - The Next Generation
Jon Lang writes: FWIW, the current proposal for aliasing blocks of ambient text is functional; it just feels a bit kludgey, Why? To me it seems the opposite: what could be more natural for delimiting a block of code than braces? and I'm a bit bothered by the fact that you can't alias any ambient text other than a code block. Can't is a bit strong: it's more that if you want to quote an arbitrary portion of code then you need to add some braces around it. But those braces are unlikely to harm the program. The exception is if you want to quote an 'unbalanced' portion of code, for example the start of a loop but not the entire loop. Do you consider that to be likely? how about saying that an ambient code alias is normally terminated by the next blank line or Pod directive (as per =for) Braces are more robust than blank lines; if aliasing a brace-delimited block I may unthinkingly edit it to have a blank line in the middle of it, on the basis that the blank line isn't significant to perl. (Whereas if I edit the braces then I've changed the program as well as its docs.) An alternative would be to have blank-line termination for an alias which _doesn't_ start with a brace (that is, doesn't have an opening brace on the following non-blank line). However that would likely confuse somebody who happens to add a brace to the line following the alias directive (perhaps inside a quoted string, or changing the brackets on a hash look-up, or in a regex) and unwittingly changes the alias from several lines to just a few characters in the middle of that line. Terminating at a Pod directive sounds plausible, unless anybody can think of a good reason to be quoting Pod as part of code? Let's see what others think. OK. I like the braces. I suggest initially only providing for braces, but with the possibility of later adding options to indicate other termination points if in practice there turn out to be many situations where the braces don't work well. Smylers
Re: S26 - The Next Generation
Smylers wrote:
Jon Lang writes:
FWIW, the current proposal for aliasing blocks of ambient text is
functional; it just feels a bit kludgey,
Why? To me it seems the opposite: what could be more natural for
delimiting a block of code than braces?
Because sometimes you'll want to capture only part of a block of code,
or a little bit more than a block of code. In short, what you want
for documentation purposes won't always align with the conceptual
structure of the ambient code. I don't like the idea of being
required to break the code up into blocks whose only purpose is
documentation: if you're breaking the ambient code up into chunks for
documentation purposes, it should _look_ like the code is being broken
up into chunks for documentation purposes. Using Pod tricks for
denoting the start and end of aliased ambient text does that; using a
Perl block doesn't.
and I'm a bit bothered by the fact that you can't alias any ambient
text other than a code block.
Can't is a bit strong: it's more that if you want to quote an
arbitrary portion of code then you need to add some braces around it.
But those braces are unlikely to harm the program.
The exception is if you want to quote an 'unbalanced' portion of code,
for example the start of a loop but not the entire loop. Do you
consider that to be likely?
Actually, yes; I do.
how about saying that an ambient code alias is normally
terminated by the next blank line or Pod directive (as per =for)
Braces are more robust than blank lines; if aliasing a brace-delimited
block I may unthinkingly edit it to have a blank line in the middle of
it, on the basis that the blank line isn't significant to perl.
And =begin blocks are more robust than =for blocks in the same way.
Perl may not care about blank lines; but Pod does. And the author of
a file with both Perl and Pod in it is being remiss in his duties if
he doesn't consider both paradigms. Incidently, note that declarator
blocks already behave this way in Pod: the presence or absence of a
blank line determines the code to which it gets attached.
(Whereas if I edit the braces then I've changed the program as well as
its docs.)
Right. If the braces weren't part of the ambient code, and were there
merely to delineate the aliased text, I'd have less of a problem with
them. In fact, my main problem with them at that point would be how
much they look like a code block without being one, and the confusion
that's sure to arise.
Let's see what others think.
OK.
I like the braces. I suggest initially only providing for braces, but
with the possibility of later adding options to indicate other
termination points if in practice there turn out to be many situations
where the braces don't work well.
I like the idea of using the braces if they're there, and using
something else if they're not. Again, my concern is is being forced
to alias an entire code block, never anything more or less; I'm not
opposed to being _able_ to alias an entire code block, and I'm
especially not opposed to being able to do so in a simple and
intuitive manner.
But let me propose something for the absence of braces case:
introduce a new kind of delimiter into Perl - something that works
like an embedded comment, except that it doesn't actually comment
anything out. In the absence of a curly brace at the start of the
next line of code, a code alias will bind to the first document tag
that it finds, that isn't already claimed by another =alias directive.
For example:
=alias loop
#:[[
=alias loop-head
loop #:[($i = 1; $i $j; $i *= 2)]
=alias loop-body
{
DoSomething($i);
}
]]
In this example, I'm using #:[...] as a stand-in for the
documentation tag syntax. As such,
loop is aliased to:
loop ($i = 1; $i $j; $i *= 2)
{
DoSomething($i);
}
loop-head is aliased to:
($i = 1; $i $j; $i *= 2)
And loop-body is aliased to:
{
DoSomething($i);
}
I'm not fond of the document tag syntax used in the above example;
it looks a little bit too much like a comment. But whatever does get
used, it should be brief and distinct.
And since we're talking about connecting code and documentation, it's
possible that we might want to have this kind of alias be a special
case of the declaration block rather than a stand-alone directive,
using similar rules to determine what to alias (but focused on code
blocks and doc tags rather than declarators).
I've got to run right now; but I've more thoughts that just got
triggered by this. I'll get back to you as soon as I can.
--
Jonathan Dataweaver Lang
Re: S26 - The Next Generation
Moritz wrote:
However it seems we have to pay a price: each act of rendering a Pod
file actually means executing the program that's being documented (at
least the BEGIN blocks and other stuff that happens at compile time),
with all the security risks implied. So we'll need a *very* good
sandbox. Is that worth it?
I believe so. The sheer range of approaches that people said they wanted
Pod to support made it impossible for Pod to support anyone, unless
everyone can configure Pod directly. The choice then becomes: do we
provide Pod with a DSL for configuration, or do we just use
Perl 6 as its metalanguage? The answer seemed pretty obvious then.
I'm certainly not smart enough to design a config language that's powerful
enough to do everything everyone wants documentation-wise. But Larry is.
And already did. ;-)
Sure, there are downsides: Pod becomes much more tightly tied to Perl 6.
And the black hats can indeed do bad things with it.
But, you know, the bad guys have been able to do that with CPAN modules
for a long time now, and the incidence of that happening is vanishingly
small. I'm prepared to bet that most people who download something from
CPAN don't scour the source checking for system('rm -rf /')'s, nor do
they run that code in a sandbox.
And the people who *do* take such precautions will simply start to do
the same thing for any documented code (or coded documentation :-). Or
maybe the sandbox will just be an option to disable any DOC blocks
except the default one. Or else maybe perl -doc will just run under an
augmented taint mode that suspects not just anything that emerges from
an input op, but also anything created in a DOC'd command.
Two minor comments:
A valid identifier is a sequence of alphanumerics and/or
underscores, beginning with an alphabetic or underscore
Is there a good reason to deviate from Perl 6's definition of an
identifier? For the sake of consistentcy I'd just say that the Perl 6 rules
apply.
Great idea. Should definitely be that way. Patch applied.
sub fu ( #= This text stored in Cfu.WHY
This seems to be ignorant of multi subs.
Not ignorant of. Just not an example of. ;-)
If I write
multi sub fu () { #= some Pod
Then fu is a multi, not a particular candidate. Does it actually
attach to the .WHY of the candidate? Or of the multi?
Of the particular candidate. I'll make that clearer.
(If you want to document the entire multi, attach the documentation to
the proto.)
Damian
Re: S26 - The Next Generation
Raiph commented: Couldn't the pod processing be encapsulated, perhaps in PGE/NQP, so that it could be reused in a different Parrot language, provided that said language supports declarators and comments, or even just comments (if one downgrades the impact of encountering an attached comment that has no declarator to a warning). The latter would fully restore the generic applicability of the POD 5 parser, right? While I'm all in favour of other languages using Pod as a documentation format, I think that's unlikely. Pod says that anything of the form: =identfiier *anywhere* as the first non-whitespace of a line, is considered a Pod directive. I can't see many other language designers being willing to limit their assignment statements that way. While I like the design, and I think it's near enough complete, and I think a reader who knows perl and pod well could understand your current description of that design, I think it could do with a major rewrite to make it less confusing to work out what you really mean as against what's currently written. ;) However, I think it's too early to attempt such a rewrite, or even to comment on specific problems; I plan to wait another couple weeks for some list back-and-forth before commenting further about clarity and/or proposing edits and/or providing patches. I agree that a rewrite would certainly help it. And will be happy to kibitz anyone who volunteers to do so! ;-) Or, of course, to accept patches. You don't say whether attached pod allows for configuration info or formatting codes. It does. I don't say it doesn't, and I do show attached comments with it (e.g. the $chainsaw example). I'll make it explicit however. (Incidentally, .WHY seems a bit too cute; what about .DOC or .POD? Same with .WHEREFORE; my boring suggestion is .CODE.) I think you're going to have to take that up with Larry. Presumably the WHO, HOW, WHERE, WHENCE, etc. should go too? Personally (and I say this as the guy who pioneered you think that's cute now... ;-) I think the interrogatives work very well, especially because they stay so well out of the way of anything a sane person (pace Larry) would use to name an ordinary method. Declarator aliases, as specced, seem to me the weakest part of the design. Declarator aliases seem to only allow one my, one has, etc. in a given context. We could certainly consider allowing a fourth form of alias like so: =alias IDENTIFIER DECLARATOR which would use the specified identifier as the alias's name, rather than the declarator. Lets see what other people think. Having to use non-attached pod syntax to do an attached thing seems very weird. I think they have to be different, because they do opposite things...or at least things in opposite directions. A declarator block says this Pod belongs to this code; an alias says this code can be referred to in subsequent Pod. I'd be happy to be proved wrong if someone can come up with a better mechanism than aliases that still allows us to pull code into Pod. Having to use aliases at all to refer to things that the Perl 6 compiler already has a name for seems like an ugly/heavyweight/suboptimal approach. I think aliases are essential. We need a way of referring to ambient code within Pod, without the Podder having to write more code to get it. Damian
Re: S26 - The Next Generation
Jonathan Dataweaver Lang enquired:
Will ther be any ambiguity between Pod and wraparound operators that
begin with =?
No. Lines that start with an '=' that is *immediately* followed by an
identifier are always Pod. If there's a space after the '=' it's always
an assignment. You could *create* an ambiguity, by defining an operator
such as infix:=x but then you get precisely what you deserve. ;-)
if really_long_expression
== value { ... } # Pod, or equality operator?
Always equality. Pod is always =IDENT. Only.
Note the recent revisions to how Perl comments work - in particular,
an embedded comment is now spelled #`[ ... ]. Should embedded
attached Pod be spelled as #=`[ ... ]?
Larry and I discussed this and concluded that #=[ is better.
I can see the logic of #`[= but I just can't see the aesthetics of it.
I'd much rather have to only look at the second character to determine
it's Pod, not a vanilla comment. Besides, I think people will simply learn
that #symbol[ is an embedded comment, where symbol specifies
what kind of comment it is (I can certainly envisage other kinds
besides just vanilla and Pod-flavoured)
Damian
Re: S26 - The Next Generation
Could we also get =numbered and =term directives that are equivalent to =item :numbered and =item :term, respectively, for use with abbreviated blocks? E.g.: =numbered First Item =numbered Second Item =numbered Third Item That's just: =item # First Item =item # Second Item =item # Third Item or even just: =item# First Item =item# Second Item =item# Third Item =term First Name Definition =term Second Name Definition This doesn't work, because it doesn't conform to the general syntax of abbreviated blocks (which is that the content starts immediately after the typename). The term of a term/definition is basically a very complicated bullet point, and hence needs to be configured with an option. Of course, we could make a special exemption to the general syntax, or say that in this one case the first line of content is special, but I'm *really* loathe to inject special cases when a general mechanism already exists. Within tables, you should probably replace whitespace with multiple whitespace as a column delimiter; otherwise, the space between two words in an identifier would trigger a new column: Indeed. That was both the intention and the implementation in Perl6::Perldoc, but it definitely needs to be mentioned explicitly. Thank-you. When using the code block alias, are the outermost curly braces considered to be part of the ambient code? Yes. All ambient code is actual code. Why is =END a block, and not a directive? Damn good question. I can't think of any reason off the top of my head. I'll need to ponder that. Damian
Re: S26 - The Next Generation
On Wed, Aug 19, 2009 at 11:54 AM, Damian Conwaydam...@conway.org wrote: Moritz wrote: However it seems we have to pay a price: each act of rendering a Pod file actually means executing the program that's being documented (at least the BEGIN blocks and other stuff that happens at compile time), with all the security risks implied. So we'll need a *very* good sandbox. Is that worth it? I believe so. The sheer range of approaches that people said they wanted Pod to support made it impossible for Pod to support anyone, unless everyone can configure Pod directly. The choice then becomes: do we provide Pod with a DSL for configuration, or do we just use Perl 6 as its metalanguage? The answer seemed pretty obvious then. Pod itself is a DSL. If we're committed to giving guns to books, can we default to having the safety on? Can it be so that 'perl6doc foo.pl' does not execute any code without an option to allow it? Module authors can use it to generate files to go with the distribution. 'make install' can use it to generate docs with locally-set values in them. Casual browsers can stay safe. Perl 5 programmers are sometimes surprised to find that 'perl -c strange.pl' can execute code. Imagine their surprise to find that 'perl6doc' does too. Kyle.
Re: S26 - The Next Generation
On Wed, Aug 19, 2009 at 11:03, Kyle Hasselbacherkyl...@gmail.com wrote: Perl 5 programmers are sometimes surprised to find that 'perl -c strange.pl' can execute code. Imagine their surprise to find that 'perl6doc' does too. this is why it's spelled 'perl6 --doc', which should give you some hint that you're running the compiler, just as 'perl -c' does, and 'perldoc' doesn't. ~jerry
Re: S26 - The Next Generation
Kyle suggested: Pod itself is a DSL. Sure. But to allow arbitrary processing and rendering of Pod, a DSL isn't enough. If we're committed to giving guns to books, can we default to having the safety on? Can it be so that 'perl6doc foo.pl' does not execute any code without an option to allow it? There is no perl6doc. There is only: perl6 -doc That is, running the Perl interpreter in a special mode to get documentation. Perl 5 programmers are sometimes surprised to find that 'perl -c strange.pl' can execute code. Imagine their surprise to find that 'perl6doc' does too. But the reason will be exactly the same. Namely, because in Perl you can't tell what's documentation and what's code until you parse the mixture. And you can't parse Perl (5 or 6) without executing stuff. Look, I'm sure we *will* have a safety mode of parsing Pod (maybe: perl -undoc) But it can't be on by default, otherwise no-one can write anything but vanilla Pod and expect it to work. It's like saying that 'use' is potentially dangerous (which it *is*) so can we have it off by default. In Perl, the answer has to be no. Damian
Re: S26 - The Next Generation
Damian Conway wrote: When using the code block alias, are the outermost curly braces considered to be part of the ambient code? Yes. All ambient code is actual code. OK. Let me propose an alternative (which I expect will be immediately shot down): Allow '=begin alias', '=end alias', and '=for alias' as special cases: the Perl parser makes an exception for them and doesn't treat them as the start or end of POD Blocks, merely as single-line directives; but the Pod parser treats them as normal Pod Blocks, with the contents being attached to the alias. Net result: said contents count both as ambient code and as aliased text. Benefits: you can alias any ambient code that you want, as long as it consists of one or more full lines; and your method for delimiting the alias is one that Pod writers will be quite use to. Drawback: the Perl parser will need to look forward a bit further before deciding how much ambient commentary there is. -- Jonathan Dataweaver Lang
Re: S26 - The Next Generation
Jonathan Dataweaver Lang proposed: OK. Let me propose an alternative (which I expect will be immediately shot down): BANG! ;-) Allow '=begin alias', '=end alias', and '=for alias' as special cases: the Perl parser makes an exception for them and doesn't treat them as the start or end of POD Blocks, merely as single-line directives; but the Pod parser treats them as normal Pod Blocks, with the contents being attached to the alias. Well, clearly I'm not going to be in favour of introducing exceptions to the general syntax. However, I had originally thought that we should have =alias and =dealias directives to delimit code extractions. In the end I liked the use of the code's own delimiters better, but I guess if people preferred to have two directives as delimiters, we could consider that instead. Let's see what others think. Damian
Re: S26 - The Next Generation
FWIW, the current proposal for aliasing blocks of ambient text is
functional; it just feels a bit kludgey, and I'm a bit bothered by the
fact that you can't alias any ambient text other than a code block.
On Wed, Aug 19, 2009 at 11:29 AM, Damian Conwaydam...@conway.org wrote:
Jonathan Dataweaver Lang proposed:
OK. Let me propose an alternative (which I expect will be immediately
shot down):
BANG!
;-)
D'oh!
Allow '=begin alias', '=end alias', and '=for alias' as special cases:
the Perl parser makes an exception for them and doesn't treat them as
the start or end of POD Blocks, merely as single-line directives; but
the Pod parser treats them as normal Pod Blocks, with the contents
being attached to the alias.
Well, clearly I'm not going to be in favour of introducing exceptions to
the general syntax.
However, I had originally thought that we should have =alias and
=dealias directives to delimit code extractions. In the end I liked the
use of the code's own delimiters better, but I guess if people preferred
to have two directives as delimiters, we could consider that instead.
What I liked the most about my proposal was that it allowed for a
blank line termination form as well as an explicit directive
termination form. On review, '=for alias' would have been redundant
with '=alias' (although I don't think that redundancy hurts). And
again, the Pod coder would be able to think in the same terms that he
does for ordinary blocks.
But assuming for the moment that the pseudo-block idea is off the
table, how about saying that an ambient code alias is normally
terminated by the next blank line or Pod directive (as per =for)
unless you give it a :begin adverb, in which case it terminates with
an appropriately nested =alias name :end directive:
=alias outer :begin
while (...) {
=alias inner
blah blah blah
}
=alias outer :end
Unless there's some reason why adverbs don't work for =alias
directives, that's fully consistent with normal syntax. OTOH, that's
exactly what the problem would be, isn't it? '=alias outer :begin'
would be parsed as an inline alias, where outer is equated with
:begin. So how about borrowing from your earlier example of
numbered items, and identifying explicitly terminated blocks with a +
or - immediately following the '=alias':
=alias+ outer
while (...) {
=alias inner
blah blah blah
}
=alias- outer
I'm also considering a more radical possibility whereas the ambient
code has a means of tagging portions of itself for Pod inclusion.
I'll think it through some more and then offer a proposal.
Still, I think that treating =alias as a block when it has only one
argument, and as a directive when it has none or two, would be more
user-friendly (though admittedly more hostile to the guy coding the
Pod Parser) than any of these alternatives.
Let's see what others think.
OK.
--
Jonathan Dataweaver Lang
Re: S26 - The Next Generation
On 2009-Aug-18, at 3:29 am, Jan Ingvoldstad wrote: In general, executable documentation is a bad thing. It's been shown to be a bad thing many times over. Well, tons of programs have --help options, which could be considered executable documentation, and it's very useful. Emacs brags about being self-documenting. It's worth it because it's more work the computer can do instead of humans (and often do a lot better). It's annoying when a printed book says the default setting is $foo when it isn't because somebody changed the defaults, or the config file is at $some/$path when it isn't because it was installed using a non-standard layout -- but it's understandable, because there's not much you can do about that. It's a lot more frustrating when you're looking at docs on a programmable computer that actually knows the real settings/paths/etc. and *could* tell you, but doesn't. But it's a lot more than that: although it can help the end-user, it also helps authors. I can weave together my (il)literate POD in the most convoluted way Pod6::Order::Labyrinthine can handle. I can have it pull values out of my code so that's impossible for the docs to get out of date because I forgot to change them. That's still a big help even if my end users look only at a static copy of the docs once they're produced. If we absolutely must have some sort of executable documentation, then if I could, I would insist that it wouldn't be a feature complete language. That is: absolutely no IO in the language, no way of executing code that's foreign to the doc, and so on. Well, perl-doc can't run any POD-executing modules that never get installed. But surely it's possible to forbid IO, no? Disallow any actual IO functions, as well as anything that could be used to sneak them in (eval). I guess you'd want to allow Perl itself to load installed modules (but maybe nothing from the current dir, or outside the official library location). Having perl-doc run in lock-down mode, or run in display-precompiled-static-file-only mode by default might be a good idea, though I'm not convinced it's completely necessary. -David
Re: S26 - The Next Generation
On Sun, Aug 16, 2009 at 3:26 PM, Damian Conwaydam...@conway.org wrote: * The DOC statement prefix constrains any block to which it is applied (including BEGIN, CHECK, INIT and similar) to run only if -doc is specified on the commandline * You can tell if you're running under -doc by checking $?DOC Does this mean I can run code on some other machine when someone on that machine reads my documentation? Kyle.
Re: S26 - The Next Generation
Damian Conway wrote:
It's not yet committed, as there will (no doubt) be much discussion
first. I apologize in advance: I am still travelling on my annual world
tour, so my ability to participate in this discussion will be limited
and erratic.
In the spirit of ask for forgiveness rather than permission I'd
suggest to commit it early. People on #perl6 have been asking where it
is already, since it's not at the usual location[tm].
Of course, all comments, suggestions, and patches are most welcome.
Then let me start with a huge praise: to me it seems much more practical
to the Pod writer than the previous version. I appreciate the huge
effort that has surely flown into it.
However it seems we have to pay a price: each act of rendering a Pod
file actually means executing the program that's being documented (at
least the BEGIN blocks and other stuff that happens at compile time),
with all the security risks implied. So we'll need a *very* good
sandbox. Is that worth it?
Two minor comments:
ll 99:
followed by a valid identifierN
A valid identifier is a sequence of alphanumerics and/or
underscores, beginning with an alphabetic or underscore
Is there a good reason to deviate from Perl 6's definition of an
identifier? For the sake of consistentcy I'd just say that the Perl 6 rules
apply.
ll 311:
sub fu ( #= This text stored in Cfu.WHY
This seems to be ignorant of multi subs. If I write
multi sub fu () {#= some Pod
Then fu is a multi, not a particular candidate. Does it actually attach to
the .WHY of the candidate? Or of the multi?
Cheers,
Moritz
Re: S26 - The Next Generation
However it seems we have to pay a price: each act of rendering a Pod file actually means executing the program that's being documented (at least the BEGIN blocks and other stuff that happens at compile time), with all the security risks implied. So we'll need a *very* good sandbox. Is that worth it? From the spec: However, during parsing and initialization under K-doc, the interpreter only executes those CBEGIN, CCHECK, and CINIT blocks (and equivalents, such as Cuse statements and subroutine declarations) that are preceded by the special prefix: CDOC -- love, raiph
Re: S26 - The Next Generation
On Aug 17, 2009, at 14:27 , Moritz Lenz wrote: ll 99: followed by a valid identifierN A valid identifier is a sequence of alphanumerics and/or underscores, beginning with an alphabetic or underscore Is there a good reason to deviate from Perl 6's definition of an identifier? For the sake of consistentcy I'd just say that the Perl 6 rules apply. It occurs to me that *if* you are executing/evaluating (part of) the source, then it could be argued that an identifier should be defined by whatever language the parser ends up running, which might not be perl6. -- brandon s. allbery [solaris,freebsd,perl,pugs,haskell] allb...@kf8nh.com system administrator [openafs,heimdal,too many hats] allb...@ece.cmu.edu electrical and computer engineering, carnegie mellon universityKF8NH PGP.sig Description: This is a digitally signed message part
Re: S26 - The Next Generation
On Aug 17, 2009, at 14:34 , raiph mellor wrote:
However it seems we have to pay a price: each act of rendering a Pod
file actually means executing the program that's being documented (at
least the BEGIN blocks and other stuff that happens at compile time),
with all the security risks implied. So we'll need a *very* good
sandbox. Is that worth it?
From the spec:
However, during parsing and initialization under K-doc, the
interpreter only executes those CBEGIN, CCHECK, and
CINIT blocks (and equivalents, such as Cuse statements
and subroutine declarations) that are preceded by the special
prefix: CDOC
Nonetheless, DOC INIT { system rm -rf . } (or etc.) would be
unfortunate.
--
brandon s. allbery [solaris,freebsd,perl,pugs,haskell] allb...@kf8nh.com
system administrator [openafs,heimdal,too many hats] allb...@ece.cmu.edu
electrical and computer engineering, carnegie mellon universityKF8NH
PGP.sig
Description: This is a digitally signed message part
Re: S26 - The Next Generation
Nonetheless, DOC INIT { system rm -rf . } (or etc.) would be unfortunate.
Gotcha. Perhaps something like perl6 -DOC is needed to execute DOC
blocks in the file passed on the command line and files it use's,
whereas perl6 -doc only processes DOC blocks in the Setting or its
use'd files, and merely parses but does not execute DOC blocks in the
file passed on the command line and files it use's.
--
love, raiph
Re: S26 - The Next Generation
raiph mellor wrote: However it seems we have to pay a price: each act of rendering a Pod file actually means executing the program that's being documented (at least the BEGIN blocks and other stuff that happens at compile time), with all the security risks implied. So we'll need a *very* good sandbox. Is that worth it? From the spec: However, during parsing and initialization under K-doc, the interpreter only executes those CBEGIN, CCHECK, and CINIT blocks (and equivalents, such as Cuse statements and subroutine declarations) that are preceded by the special prefix: CDOC I didn't read that part, and I wonder how useful it is. Basically to produce a correct parse, any 'use' directive has to be executed, otherwise you can't know if something is a type name, a subroutine name or what not. Also modules can export special syntax, causing the parse to be significantly altered. Cheers, Moritz
Re: S26 - The Next Generation
On Sun, Aug 16, 2009 at 1:26 PM, Damian Conwaydam...@conway.org wrote:
* This means Pod can be indented; the = is no longer tied to the
first column. The indentation preceding the opening = (using the
($?TABSTOP // 8) rule, as for heredocs) now specifies the zeroth
column of the Pod block.
Will ther be any ambiguity between Pod and wraparound operators that
begin with =? e.g.,
my Dog $spot
= new Dog; # Pod, or Perl assignment?
if really_long_expression
== value { ... } # Pod, or equality operator?
* In addition to delimited, paragraphed, and abbreviated Pod blocks,
documentation can now be specified in a fourth form:
my $declared_thing; #= Pod here until end of line
sub declared_thing () { #=[ Pod here
until matching
closing bracket
]
...
}
Note the recent revisions to how Perl comments work - in particular,
an embedded comment is now spelled #`[ ... ]. Should embedded
attached Pod be spelled as #=`[ ... ]? My preference would be to
simply say that if the very first character within a comment is an =,
then it becomes a Pod attachment. That is, we're not dealing with a
variation of the Pod Comment syntax (i.e., s/#/#=/); rather, we're
dealing with a special use of a normal comment. Thus, an embedded Pod
attachment would be written as #`[=...]. The main benefit of this
would be that if any further refinements occur to Perl's comment
syntax, Pod will adapt to those changes seamlessly[1]. As well, this
would help with any effort that might be made to integrate the use of
Pod into other languages: e.g., Javascript-with-Pod would handle a Pod
attachment as /*=...*/ or //=... (for embedded and end-of-line
comments, respectively).
--
Jonathan Dataweaver Lang
[1] Not to derail the conversation, but I would consider this to be
another argument in favor of the proposed '(#...)' syntax for embedded
comments: with this syntax, an embedded Pod attachment would be
spelled '(#=...)'. Much more aesthetically pleasing.
Re: S26 - The Next Generation
Could we also get =numbered and =term directives that are equivalent to =item :numbered and =item :term, respectively, for use with abbreviated blocks? E.g.: =numbered First Item =numbered Second Item =numbered Third Item =term First Name Definition =term Second Name Definition Within tables, you should probably replace whitespace with multiple whitespace as a column delimiter; otherwise, the space between two words in an identifier would trigger a new column: column 1 column 2 ^^ ^ ^^ ^ (Each group of ^'s would be a separate column.) When using the code block alias, are the outermost curly braces considered to be part of the ambient code? Why is =END a block, and not a directive? -- Jonathan Dataweaver Lang
Re: S26 - The Next Generation
On 2009-Aug-17, at 12:27 pm, Moritz Lenz wrote: However it seems we have to pay a price: each act of rendering a Pod file actually means executing the program that's being documented (at least the BEGIN blocks and other stuff that happens at compile time), with all the security risks implied. So we'll need a *very* good sandbox. Is that worth it? Yes. In general, if you've installed a module, it's because you're going to use it, and you already trust it. So this is a problem only if you're looking at the documentation for the first time to decide whether you do want to use the module (and didn't already read the docs on CPAN.org first or something). Of course, CPAN will need a static copy of the docs anyway, so the solution is that authors should provide a static file (preferably in a few formats, at least text and HTML). Sites like CPAN will probably make a static doc file a requirement, and even the cpan shell could warn users about any modules that don't include static docs -- in fact, I think it would be reasonable to refuse to install such modules by default. -David
Re: S26 - The Next Generation
On 2009-Aug-16, at 2:26 pm, Damian Conway wrote: It's Sunday evening and, as promised, here's the new draft of S26. Yay! (To the contents, that is, not to the posting of it. Well, to the posting too, since otherwise it would have been much harder to read.) Perl that accesses $=POD and/or the .WHY and .WHEREFORE methods My favourite part is that it's actually called WHEREFORE. (Take that, all-other-programming-languages!) Hopefully this is something close to the final draft...and something that every stakeholder and faction in this long discussion can dislike equally. ;-) I like it very much. But don't worry, I'll think of something to quibble about! -David P.S. to format it using perldoc2xhtml, I had to change the =begin item at line 589 to =for item.
Re: S26 - The Next Generation
Damian Conway wrote: It's Sunday evening and, as promised, here's the new draft of S26. That's great to see. And from the executive summary, it seems to include a lot of the features or behaviors I was suggesting in the comments as preserved meta-data thread. I will look at this new S26 more closely soon. But one thing I'm not sure whether or not it was addressed is regards to whether free-form documentation is still supported or can be effectively combined with embedding documentation into the places that it is documenting. -- Darren Duncan
Re: S26 - The Next Generation
Darren Duncan asked:
But one thing I'm not sure whether or not it was addressed is regards to
whether free-form documentation is still supported or can be effectively
combined with embedding documentation into the places that it is
documenting.
Yes and yes.
Normal Pod blocks weren't mentioned in the executive summary because
they haven't changed. Except that they got much better, because now you
can indent them to match the layout of the code they're interleaving.
Or, indeed, indent them simply to indicate the Pod's own lexical
structure.
The Necrotelecomnicon example was originally written like so
(before I removed the Pod blocks...to keep the example properly
focussed):
=head2 IPC magic
=para
The base class for doing deep and dangerous things with IPC
is
#= Base class for comms necromancy hierarchy
class Magic::Necrotelecomnicon {
has $.elemental; #= Source of all power
has $!true_name; # Source of all self-protection (not documented)
method cast(Spell $s)
#= Initiate a specified spell normally
{
do_raw_magic($s);
}
#= Initiate a specified spell abnormally
method kast(Spell $s) {
do_raw_magic($s, :alternative);
}
}
which, by default (and in the absence of any semi-literate or
OO-bsessive modules one might explicitly CDOC use),
will simply produce something like:
IPC Magic
The base class for doing deep and dangerous things with
IPC is
Name: Magic::Necrotelecomnicon:
Desc: Base class for comms necromancy hierarchy
Attrs:
.elemental : Source of all power
Methods:
.cast(Spell $s) : Initiate a specified spell normally
.kast(Spell $s) : Initiate a specified spell abnormally
Damian
