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.
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
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
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
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
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
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)
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
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
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.
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:
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
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
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
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
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
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
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
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
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
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
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*
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
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
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
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
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
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
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
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
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
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
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
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?
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
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
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
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
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
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
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
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
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
43 matches
Mail list logo
