Re: S26 - The Next Generation
Jon Lang asked: Not actually S26; but closely related: should $=POD and .WHY be read-only? I had assumed so. Also, should there be other Pod variables besides $=POD? If so, which ones? The original idea was that every Pod block with any kind of TYPENAME would be available as $=TYPENAME. For example: $=USAGE, $=OPTIONS, $=SYNOPSIS, etc. In particular, $=DATA is likely to be heavily used. 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.) We pretty much have to provide a way for a Pod object to know what Perl object it's associated with. The whole point is to create an open-ended mechanism to allow people to twiddle how Pod is rendered. To do that, they need to be able to walk the documentation tree (a.k.a. $=POD) and extract useful information from any class, code, or variable declarations associated with a particular comment-style node in the doctree. Damian
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
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 Tue, Aug 18, 2009 at 3:47 AM, David Greendavid.gr...@telus.net wrote: 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. Why is it worth it? In general, executable documentation is a bad thing. It's been shown to be a bad thing many times over. 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. -- Jan
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
On Sun, Aug 16, 2009 at 3:26 PM, Damian Conwaydam...@conway.org wrote: It's Sunday evening and, as promised, here's the new draft of S26. Thanks! After an initial read thru the summary and spec my overall reaction to the new pod is whirled peas!. :) * Hence it must always parsed using full Perl 6 grammar: perl6 -doc 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? Hopefully this is something close to the final draft...and something that every stakeholder and faction in this long discussion can dislike equally. ;-) 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. The two design questions/comments I have for now are: You don't say whether attached pod allows for configuration info or formatting codes. I'm guessing your intent is no on both accounts. However, presumably the pod parser could process config at the start of attached pod and attach just the text after the config to the .WHY. (Incidentally, .WHY seems a bit too cute; what about .DOC or .POD? Same with .WHEREFORE; my boring suggestion is .CODE.) And formatting codes could presumably be interpreted by renderers that chose to do so. 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. Having to use non-attached pod syntax to do an attached thing seems very weird. 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. Anyhoo, thanks for the time spent and great design skills that are so evident in this new spec. :) -- love, raiph
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