Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
Mark Overmeer asked:
* Pod and Perl (or any other ambient source code) are to be syntactically
separated, even when there are semantic interconnections
Why? Who says that?
Me. :-)
* Perl 6 will be able to access ambient Pod via $=POD (and other
$=WHATEVER variables)
Cannot find anything about that in S26
Try S02.
Yes, and that is one of the things which worries me most *You can*.
It's full freedom, like XML, and without a convention everyone may
think-up there own way of documenting the same kinds of code elements.
No. There *will* be conventions, which will be defined by the behaviour of the
standard documentation tools that we create.
The whole point of the debate, is that IMO the focus (and only real
challenge) is this task: combine information about the Perl program
and the documentation about those elements in an as good as feasible
way. All the rest is just syntax. On the moment, I am not convinced
that this task sufficiently facilitated. Many features in POD6 will
complicate this task too much.
Naturally, having spent a great deal of time to redesign Pod specifically to
facilitate better and easier documentation, I disagree. :-)
And what I would like to see is that doc-tree and Perl6 AST are one.
And I am strongly opposed to that as the only alternative.
That said, it will certainly be *possible*.
i.e. it is not a valid argument: expressions and regexes are integrated.
Sure, but you're arguing from a false analogy. Expressions and regexes are the
same kind of thing: executable specifications. So of course they're
integrated. Documentation is a different kind of thing...so naturally it
should be dis-integrated. ;-)
IMO it is: the issue is to have sufficiently integrety in code and markup
to be able to create documentation-generating tools which produce enough
quality. And at the same time give the programmer the mimimal burden on
writing documentation, to increase the chance that it is present and good.
[this last sentence is my only design criterium]
And I claim the current design fully facilitates that.
Like so:
class Mail::Message {
=PURPOSE Base class for message types
has $msgid;
=for PURPOSE
The (internet wide) unique string which identifies this
message object. May be undef as long as the message is
begin composed.
has $content_type = 'text/plain';
}
This is just a syntax transformation, where I can live with. No
problem. But it is not the whole story. "PURPOSE" is not in S26.
It is *now* ;-)
Remember, we're still designing and documenting that design. Hence the careful
wording of S26:
All other uppercase block typenames are reserved...
^^^
Standard semantic blocks include:
^^^
Ultimately, the complete set of semantic blocks will be defined by the scope
and behaviour of the documentation tools we create.
In my "vision", the example is complete. Everything else is determined
by the processing tools and style sheets.
Agreed.
Do not understand me wrong: for the choosen approach to produce
documentation, you did an excellent job with the specification. It
is well written, well documented, and even implemented.
But I do not see how this approach contributes to the homogeneous set
of manual-pages for Perl modules that the end-user prefers.
It does so by providing a standard--and extensible--mark-up notation and a
well-structured document object model (which includes representations for
interspersed code), as well as standardized parsing tools from converting a
source document to an internal representation.
These features (along with Perl 6's ability to parse Perl 6 source) will make
it vastly easier to build man-page generators.
[ Damian, we didn't change our opinions a thing since the last debate
on this subject, last year, haven't we. Probably just another
holy war ]
Yes. For that very reason I don't propose to keep arguing this issue.
I certainly respect your concerns and desires. I'm merely frustrated by the
fact that I can't seem to convince you that they're actually being addressed. :-)
Damian
Re: = at Start of Line ([svn:perl6-synopsis] r14421 - doc/trunk/design/syn)
brian d foy writes: > In article > <[EMAIL PROTECTED]>, Damian > Conway <[EMAIL PROTECTED]> wrote: > > > No. It's Pod. *Any* line that begins with '=begin' always starts a Pod > > block. Always. > > As you know, one of the biggest complaints about Perl is that you have > to have a lot of special rules knowledge to figure some things out. Indeed. What's much nicer is to be able to state that a given rule "always" applies. Like Damian has just done here. Saying that C<=> at the start of a line always means Pod is much simpler than having a list of exceptions of places where it doesn't. > Also, doesn't this then limit Pod to Perl 6 (which I thought was not > the goal)? I reckon the complete opposite. > I doubt other languages will want to deal with this situation. With these new Pod rules it's possible to entirely remove Pod from a file without knowing _anything_ about the host language. (It could straightforwardly be done as an editor macro, for example.) That permits Pod to be used to document just about anything; all you need to allow it is a filter that strips off all Pod before you do anything else with the file. If Pod were to take notice of the host language's context throughout the file then this would not be possible: every language which wished to have Pod support would require its own Pod parser embedded within the languge parser. _That_ is orders of magnitude more complex than the simplicity of filtering off all Pod first, and strikes me as something other languages are much less likely to be bothered to do. Smylers
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
Mark Overmeer writes: > * Damian Conway ([EMAIL PROTECTED]) [070615 00:17]: > > > * Pod 6 is both a structural and a semantic scheme; you can specify > > both the structure of a document, and the meaning of its various > > components > > Yes, and that is one of the things which worries me most *You can*. > It's full freedom, You're concerned that an aspect of Perl 6 might have too much freedom? Isn't Perl all about giving users freedom to choose their own way of doing something? > like XML, and without a convention everyone may think-up there own way > of documenting the same kinds of code elements. Yes. But in reality many people will follow what others do, or look to follow best practices. With Perl 5 you have complete freedom as to the names of C<=head1> sections in the Pod for modules, yet in browsing Cpan it's clear that there are conventions and many people use the same headings. So not mandating a convention isn't much of a problem. Moreover, I reckon that not mandating a convention is essential. Look at what's being done with Perl 5 at the moment (not specifically Pod, just in the Perl 5 community in general) and the best practices that have sprung up in recent years (and are still evolving). People are, of their own accord, following conventions that nobody had even thought of at the time Perl 5 was released; even at the time Perl 5.6, say, was released. > In this structure, the responsibility of how things get interpreted is > not for the programmer, so consistent over all modules. We can make > search.cpan.org and manual-pages with a consistent structure. Do you really think that people can now, before Perl 6 has gained anything approaching the usage we expect, make policy for how things should be documented, such that that policy will be the best possible way of documenting everything written in Perl 6, for ever? Or even a good way? That strikes me as incredibly shortsighted, verging on arrogance by whoever comes up with the rules, and doomed to failure. Rather than trying to map out the future in detail (which is tricky), the best we can do is come up with things that are sufficiently flexible that they're capable of being used in ways we haven't yet thought of. Then when somebody, years from now, has a good idea, it will be possible for that to be implemented (and followed by others), rather than tying us to some convention set at an arbitrary point in the past. > > * To summarize the summary: > >- Use Perl for what Perl is good for (specification) > >- Use Pod for what Pod is good for (commentary) > - Use expressions where expressions are good for (calculation) > - Use regexes where regexes are good for (matching) >... > > i.e. it is not a valid argument: expressions and regexes > are integrated. Yes, but on the other side of the argument coconuts and fax machines are not integrated. I'm reasonably confident that for every pair of things which you list as being integrated I can come up with a pair which aren't; I doubt that will really assist the argument one way or t'other. > the issue is to have sufficiently integrety in code and markup > to be able to create documentation-generating tools which produce enough > quality. Damian's spec permits this. > And at the same time give the programmer the mimimal burden on writing > documentation, to increase the chance that it is present and good. You should 'Perl 6 Documentation Best Practices', with guidelines for how to use Pod. I'm sure many people would appreciate just being able to follow a template rather than having to make decisions over the small details of what to do. That way we have a convention for those that want it, but also don't tie ourselves into anything. If a particular convention gains widespread approval then peer pressure should encourage its use (in the same way that strict and warnings are currently optional in Perl 5, but in the absence of a good reason it's expected that they be used). Smylers
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
* Smylers ([EMAIL PROTECTED]) [070616 09:09]: > > * Damian Conway ([EMAIL PROTECTED]) [070615 00:17]: > > > * Pod 6 is both a structural and a semantic scheme; you can specify > > > both the structure of a document, and the meaning of its various > > > components > > > > Yes, and that is one of the things which worries me most *You can*. > > It's full freedom, > > You're concerned that an aspect of Perl 6 might have too much freedom? > Isn't Perl all about giving users freedom to choose their own way of > doing something? Why treat documentation as a second-class citizen all the time? Why have a standard syntax for regexes, and not for docs? Aren't you glad that at last we get a standard for OO programming and named parameters? The boundary between freedom and anacharchy is faint. > Yes. But in reality many people will follow what others do, or look to > follow best practices. With Perl 5 you have complete freedom as to the > names of C<=head1> sections in the Pod for modules, yet in browsing Cpan > it's clear that there are conventions and many people use the same > headings. So not mandating a convention isn't much of a problem. Well, the you are talking about the top three headers, the most. And those have a good example in standard UNIX manual-pages. So: there is a definitions for them, which most people have seen. Look at how people document how methods should be called. We, as programmers, don't worry: we can read between the lines. But most "normal" programmers we hardly ever meet, have a hard time. Is "freedom" (in some definition) so important that consistency must suffer? > Do you really think that people can now, before Perl 6 has gained > anything approaching the usage we expect, make policy for how things > should be documented, such that that policy will be the best possible > way of documenting everything written in Perl 6, for ever? Or even a > good way? There is no need to think that a documentation syntax develops differently than a programming language. So when Perl is developing, POD can develop in parallel. And, of course, documentation is for most people a well known area: at least, every program I wrote last 30 years had some form of documentation. To find a kind of common base of features you need does not require any knowledge about the language involved is quite simple. > That strikes me as incredibly shortsighted, verging on arrogance by > whoever comes up with the rules, and doomed to failure. Sorry? Not only you insult me, but you also ignore all these other languages which do have a nice and standard way of documenting. Insignificant languages, like Java, which we tend to ignore. Also Python, to name a closer neighbour. It is incredibly shortsighted to think that any experienced programmer would suggest a standard which cannot evolve, and adapt to variance in needs. What I suggest is at least some kind of suggestion how to denote the things everyone certainly needs. As I understand now, Damian is working on that. > If a particular convention gains widespread approval then peer pressure > should encourage its use (in the same way that strict and warnings are > currently optional in Perl 5, but in the absence of a good reason it's > expected that they be used). Well, "man Perl/BUGS" says: The -w switch is not mandatory. So at least some people agree that there may need some more guidance. Warnings default "on" is a good idea, just as giving people a good default documentation strategy. -- Regards, MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: = at Start of Line ([svn:perl6-synopsis] r14421 - doc/trunk/design/syn)
> brian d foy writes: >> I doubt other languages will want to deal with this situation. * Smylers ([EMAIL PROTECTED]) [070616 08:44]: > With these new Pod rules it's possible to entirely remove Pod from a > file without knowing _anything_ about the host language. (It could > straightforwardly be done as an editor macro, for example.) That > permits Pod to be used to document just about anything; all you need to > allow it is a filter that strips off all Pod before you do anything else > with the file. And then the main point: if you write documentation which is not related to Perl6 coding itself, do we really need to create just another text processor? There are already so many sofisticated text processors available! Well, ok, if you "get it for free", like with POD(5), then take that opportunity. But if the life of ordinary programmers who write documentation is complicated just to provide this feature, we are IMO on the wrong path. And why do you want easy to remove docs? Perl6 is even nicer: you can distribute it compiled; no program text and no docs! Docs in code files are much less of a "burden" than in Perl5, so the need to strip them from the code has deminished. > If Pod were to take notice of the host language's context throughout the > file then this would not be possible: every language which wished to > have Pod support would require its own Pod parser embedded within the > languge parser. _That_ is orders of magnitude more complex than the > simplicity of filtering off all Pod first, and strikes me as something > other languages are much less likely to be bothered to do. Other languages already have their own documentation system. Why do you expect them to use POD6? Why should we design POD6 with this endlessly open requirement in mind? Let's rule the World! All I try to achieve is the best possible set of documentation for end-users: consistent in structure and correct in content. To achieve this, I wish to keep the freedom and avoid the anacharchy. Correctness automatically improves where redundancy is removed. But that requires a closer doc/code entanglement than a lot of the experienced Perl people like (==are used to). -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
brian wrote:
> As you know, one of the biggest complaints about Perl is that you have
> to have a lot of special rules knowledge to figure some things out.
> Whether that is true doesn't really matter: people still complain about
> it.
>
> In this case, it will actually be true.
I don't think that's the case. I think the new approach to Pod has
exactly the opposite effect: it *eliminates* the need for a lot of
special rules and contextual understandings.
> This impacts Learning Perl 6 rather early because it's a rule that
> people need to know at the same time that we tell them that whitespace
> is insignificant.
I'm pretty sure "Learning Perl 6" won't say that. Mainly because it's
not true. Whitespace in Perl 6 isn't always insignificant, even in the
simplest examples. Indeed, whitespace is significantly less
insignificant in Perl 6 than it was in Perl 5.
> That's not really true anymore because a newline followed by an =
> followed by begin is this special case, **no matter how it shows up
> in the program**. Now there's this extra footnote to explain this
> situation, and at the level of basic syntax, we have to explain a
> lot more.
I don't think so.
There are two distinct models we're considering in this thread. The
first model is that Pod is a layer entirely syntactically separate from
Perl, and which is preprocessed out of existence before the compiler
ever sees the source of a program. Call this the "Separation model".
The second model is that Pod is an integral syntactic feature of
Perl: effectively a special kind of comment. Call this the
"Integration model".
The rule you have to teach under the Separation model is:
"Any line that starts with an = is Pod...and not part of your program."
Whereas the rule you have to teach under the Integration model is:
"Any line that starts with an = is Pod...and not part of your program
...UNLESS it's part of an assignment or comparator or inside a string
in which case it's something else
...UNLESS it's also inside a code block inside that string,
in which case it's a Pod command again
...UNLESS it's part of a nested assignment or comparator
or doubly nested inside the nested string
...UNLESS it's in a doubly nested code block
inside that nested string
...etc.
...etc."
So, for example, consider the following lines:
$var
=comment Is this Pod?qq{
=comment Is this Pod?qq{
=comment Is this Pod?qq{
}}}
Which of those are Pod and which are Perl?
Under the Separation model, they're all Pod;
under the Integration model, only one of them is.
> So, if this is the case, how will a new Perl 6 user debug a program
> failure when part of their program mysteriously disappears because
> they just happened to have =begin at the beginning of a line?
The same way they debug it when part of their program mysteriously
disappears because they just happened to have # at the beginning of a
line: by learning to distinguish between code and commentary.
Except, of course, the Pod mysteriously vanishing will be considerably
easier to debug, because ALL lines starting with =begin vanish, whereas
only some lines beginning with # do.
> Also, doesn't this then limit Pod to Perl 6 (which I thought was not
> the goal)? I doubt other languages will want to deal with this
> situation.
As Smylers so ably pointed out, enabling Pod to be parsed independently
of the underlying language syntax actually makes it vastly easier to use
Pod with other languages. All you need to do is insert a Pod-stripping
preprocessor (already written, as it happens) before the language's
compiler...as, indeed, the Perl6::Pod does for Perl 5.
The bottom line is that separated Pod conforms to a single simple rule,
which makes it:
* easy to teach: "a = in column 1 is Pod"
* not context-sensitive: "a = in column 1 is ALWAYS Pod"
* easy for humans to identify: "is there an = in the first column?"
* easy for machines to parse: "is there an = in the first column?"
* easy to use: "put a = in column 1"
* easy to avoid"keep the = out of column 1"
I truly think it works better that way :-)
Damian
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
* Damian Conway ([EMAIL PROTECTED]) [070616 08:29]: > No. There *will* be conventions, which will be defined by the behaviour > of the standard documentation tools that we create. man-page Perl6 secion BUGS: The "Damian Documentation Conventions" should have been mandatory. [Careful: this is intented to be a pun] > >[ ... Probably just another holy war ] > ... I'm merely frustrated by the fact that I can't seem to convince > you that they're actually being addressed. Well, let's have a drink in Vienna to ease our mutual frustrations ;-) -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
In article <[EMAIL PROTECTED]>, Damian Conway <[EMAIL PROTECTED]> wrote: [ First, I should note that whatever we end up with, that's the party line and that's what I teach, but before we end up there, I know from my years of experience teaching that certain sorts of questions are going to come up. I'm looking at this from the perspective of the student sitting in a class, not from the implementors perspective. ] > brian wrote: > > > As you know, one of the biggest complaints about Perl is that you have > > to have a lot of special rules knowledge to figure some things out. > > Whether that is true doesn't really matter: people still complain about > > it. > > > > In this case, it will actually be true. > > I don't think that's the case. I'm speaking at the programmer level, not the implementor level. For the guy in the trenches, this is a special case. This is more complexity for the guy typing code, even if it's easier syntactically for the guy writing the parser. > > This impacts Learning Perl 6 rather early because it's a rule that > > people need to know at the same time that we tell them that whitespace > > is insignificant. > > I'm pretty sure "Learning Perl 6" won't say that. Well, it won't say that if it's not true, but until pretty recently it's been mostly true. > The rule you have to teach under the Separation model is: > > "Any line that starts with an = is Pod...and not part of your program." And that's something that now comes up very early in teaching the assignment operator. > Whereas the rule you have to teach under the Integration model is: We don't teach any rule under this model, and it's been fine for over a decade :) When we do teach the current Pod, the simple rule is that Pod starts: * when Perl is expecting a new statement * there is a =something at the beginning of the line Which is considerably simpler than the long rule list you used to say the same thing (which seems a bit of FUD, honestly). > > So, if this is the case, how will a new Perl 6 user debug a program > > failure when part of their program mysteriously disappears because > > they just happened to have =begin at the beginning of a line? > > The same way they debug it when part of their program mysteriously > disappears because they just happened to have # at the beginning of a > line: > Except, of course, the Pod mysteriously vanishing will be considerably > easier to debug, because ALL lines starting with =begin vanish, whereas > only some lines beginning with # do. That's not really the case. The # only affects one line, and a pound in a literal string doesn't start a comment. People grok single line comments very well. The start of a Pod comment now affects it's line and the ones following it. > > > Also, doesn't this then limit Pod to Perl 6 (which I thought was not > > the goal)? I doubt other languages will want to deal with this > > situation. > > As Smylers so ably pointed out, enabling Pod to be parsed independently > of the underlying language syntax actually makes it vastly easier to use > Pod with other languages. Well, easy to use Pod with other languages until they try to use the assignment operator at the beginning of the line, or a = in a literal string at the beginning of a line. I know you think it's easier to teach and explain, but that's because you came up with it. The notion that a special character in a certain column means something was tough to explain to other people in FORTRAN too. There are other things to consider, and to me it looks like this design decision isn't based on what's easier for the Perl 6 programmer but what's easier for the implementors. It's not that I don't understand both sides, I just disagree about where the complexity should be.
Re: = at Start of Line ([svn:perl6-synopsis] r14421 - doc/trunk/design/syn)
In article <[EMAIL PROTECTED]>, Smylers <[EMAIL PROTECTED]> wrote: > brian d foy writes: > > > In article > > <[EMAIL PROTECTED]>, Damian > > Conway <[EMAIL PROTECTED]> wrote: > > > > > No. It's Pod. *Any* line that begins with '=begin' always starts a Pod > > > block. Always. > > > > As you know, one of the biggest complaints about Perl is that you have > > to have a lot of special rules knowledge to figure some things out. > > Indeed. What's much nicer is to be able to state that a given rule > "always" applies. Well, now explain literal strings :) This isn't about one rule, it's about an ecosystem. The rules for Pod5 always applied too, so I don't see what we've gained here as far as the simplicity of rules (but let's not go round-and-round on that since we've both already explained our positions). > Like Damian has just done here. This is a point where a lot of people will disagree, I suppose, and it's a fundamental sort of disagreeement where neither side will really be convinced otherwise. I don't think this is stubbornness either, but reflects what people value most. That is, nobody is really wrong, because we'd have to define some way to measure that, and we're really disagreeing on the yard stick. Putting aside this particular situation, the argument comes down to where does the water balloon pooch out? We haven't lost any complexity, it's just in different places. Maybe some places need less complexity and some places could stand a little more. Now, in this particular situation, Pod is much easier to extract, but literal strings now have extra baggage to consider. That's not what we're debating though. The real debate is whether you think moving the complexity around like that is worth it. Personally, extracting Pod from Perl 5 hasn't been a problem for me (and I do a lot of Pod work and write lots of custom Pod translators), so I don't think this re-distribution is worth it. I don't have to answer many questions about extracting Pod, and I don't see many normal people (meaning, not us) asking for easier ways to do this. I don't see a motivation, for the perspective of normal people, for this. When we through around terms like "natural language", normal people matter. :) You and Damian have explained the other side very well. I understand it, and it's very easy for me to understand and even deal with. We just disagree on the consequences. I tend to think that people like us are here to do the hard work so other people don't have to think about this sort of stuff, so I don't mind putting the complexity in the the parser if it takes it out of the common program elements such as strings.
Re: = at Start of Line ... solution is simple
Without replying to anyone in particular, I'll say ...
I agree with the camp that says an = at the start of a line is pod,
without exception, regardless of context.
I am also assuming that "start of the line" means there is no
whitespace to the left of the =.
I also recognize and agree with Perl 6 being sometimes whitespace sensitive.
I also found from my own experience a few months back (and I added a
test for it as t/syntax/parsing/pod_in_multi_line_exprs.t), that this
(represented with Pod 5) didn't work, but ought to (assume the 'my'
et al is flush left):
my $list = {
=pod foo docs
=cut
'foo' => sub {...},
=pod bar docs
=cut
'bar' => sub {...},
};
For technical reasons, I was constructing a bunch of routines
anonymized within a hash, rather than added to a package. A whole
file could be mostly a single hash declaration like this. I had been
expecting that I could put pod at the start of any line and it would
work, as is what seems the most intuitive. The camp that I support
would make this work.
Given this, there is an obvious (to me) solution for pod blocks in
the middle of expressions like:
my $foo
= $bar;
As the example shows, and I believe best practices espouse, you
*indent* the code line with a leading =.
This both makes the Perl code easier to understand (a continuation is
indented), and because there is leading whitespace, that = isn't
confused with pod, which is always not indented.
Simple.
And since Perl 6 does consider whitespace significant sometimes, this
is not unprecedented.
-- Darren Duncan
Re: POD <-> Code entanglement
For what it's worth, I'm a fan of the notation that NaturalDocs uses. Function: Multiply Multiplies two integers. Parameters: x - The first integer. y - The second integer. Returns: The two integers multiplied together. See Also: http://www.naturaldocs.org/ (...which happens to be written in Perl.) On 6/14/07, Mark Overmeer <[EMAIL PROTECTED]> wrote: * Thom Boyer ([EMAIL PROTECTED]) [070614 15:49]: > the existing S26, say things like: > > =Method the method synopsis goes here > =begin Parameters > =item foo is the fooiest parameter > =item bar is the barstest parameter > =end Parameters Where is the link with the code? That's the point: there is no automatic checking/avoidance of repetition. Besides, your example is not defined by S26: one can decide to use the tags, someone else chooses other names, and they then cannot be combined into one nice homogeneous set of pages. That's a horror! And if you really like above syntax, why not define =method the method synopsis goes here =option foo is the fooiest parameter =default foo 10 =requires bar is the barstest parameter Which is close to how OODoc is extending POD for Perl5. IMO We can (should) do better for Perl6. -- MarkOv Mark Overmeer MScMARKOV Solutions [EMAIL PROTECTED] [EMAIL PROTECTED] http://Mark.Overmeer.net http://solutions.overmeer.net
Quirky comments
In "[svn:perl6-synopsis] r14421 - doc/trunk/design/syn",
Damian Conway wrote:
brian wrote:
> So, if this is the case, how will a new Perl 6 user debug a program
> failure when part of their program mysteriously disappears because
> they just happened to have =begin at the beginning of a line?
The same way they debug it when part of their program mysteriously
disappears because they just happened to have # at the beginning of a
line: by learning to distinguish between code and commentary.
Except, of course, the Pod mysteriously vanishing will be considerably
easier to debug, because ALL lines starting with =begin vanish, whereas
only some lines beginning with # do.
By this reasoning, a case could be made for declaring that all lines
that begin with '#' are comments (either block or line, depending on
the second character), no matter what. That way, you'll have more
consistency between block comments and Pod Sections (which, from
Perl's perspective, should be equivalent).
The price to be paid (in both cases) is that you have to finagle any
code that would normally start a line with a '#' or '=' respectively,
such as the aforementioned block quote. Admittedly, this isn't hard
to do: starting the line with whitespace or an unspace will do the
trick. (But ending the previous line with an unspace won't, as
comments are apparently found and turned into whitespace by the
lexer.)
There is an additional price to be paid in the case of '#': you'd have
to distinguish between end-of-line comments (which cease to be
comments if placed in quotes) and line comments (which are always
comments, no matter what). In effect, you would have four kinds of
comments, not counting Pod sections:
bracketed? starts line?
yes: no:
no: line end-of-line
yes:block embedded
The semantic similarities would be as follows:
* line-oriented comments (line and block) don't care about quotes;
character-oriented comments (end-of-line and embedded) do.
* block and embedded comments continue until explicitly terminated;
line and end-of-line comments are terminated by newline.
--
Another quirk concerning comments: if I'm reading S02 correctly, C<\#>
is an unspaced comment whenever it would normally be a comment, and is
only an escaped pound sign when it would normally be a quoted pound
sign. This is one (possibly the only) case where backslashing a
special character does _not_ shut off its special behavior. As a
result, you have to quote a pound sign if you want to use it in a
pattern. If this behavior is kept (I don't care either way), it
should probably be noted in "Learning Perl 6" or the like, as a
"gotcha".
--
I also can't seem to find any means of starting a comment from within
a quote, aside from Pod Sections (and, if my first suggestion is
adopted, line and block comments). Perhaps C<\#> should count as the
start of a comment when appearing in a quote? This has the advantage
that almost every appearance of that pair of characters will act to
comment out what follows; the only exception would be when it appears
as part of the C<\\#> sequence, which is easily tested for. It does,
however, mean that you can't start a line that's within a quote with
C<\#> in order to start that line with a literal pound sign. C<\ #>
would work, though, as would indenting the quote in the case of a
heredoc.
--
Also from S02:
Although we say that the unspace hides the whitespace from the
parser, it does not hide whitespace from the lexer. As a
result, unspace is not allowed within a token.
Technically true; but what does this mean? If I were to say
foo\ bar
would the lexer generate a pair of tokens ('foo' and 'bar') that don't
have any intervening whitespace (which might be important in some
cases that involve whitespace-based disambiguation), or would it
complain about finding an unspace where it doesn't belong? I hope
that the former is true; although Larry seems to have been very
conscientious about making sure that whitespace is never forbidden
between tokens unless a dot can be placed there instead. Still,
letting unspace split tokens provides a more general solution.
--
Finally, from S02:
Since there is a newline before the first =, the POD form of
comment counts as whitespace equivalent to a newline.
This rationale doesn't hold, for two reasons. First, there is not
going to be a newline before the first = in a Pod Section if said Pod
Section starts the file. Second, the stated behavior doesn't follow
from the premise. Given the logic that Pod Sections are effectively
stripped out of the file before anything else happens, one would
expect:
say qq:to'END';
=begin comment
END
=end comment
END
to be equivalent to:
say qq:to'END';
END
instead of:
say qq:to'END';
END
However, the latter is what occurs under the current rule. I submit
that Pod Sections shouldn't be equivalent to whitespace; they should
be equivalent to empty strings. Likewise with line and block
comme
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
brian d foy wrote:
> Whereas the rule you have to teach under the Integration model is:
We don't teach any rule under this model, and it's been fine for over a
decade :)
When we do teach the current Pod, the simple rule is that Pod starts:
* when Perl is expecting a new statement
* there is a =something at the beginning of the line
Which is considerably simpler than the long rule list you used to say
the same thing (which seems a bit of FUD, honestly).
Agreed about the parenthetical. From my perspective, the proponents
of the Separation Model are overstating the difficulties inherent to
the Integration model. That said:
By the rule you give above, Pod Sections cannot be embedded in the
middle of statements. For example, given:
if
a = 5
{
say "ouch!"
}
you couldn't insert a Pod Section between the first and second lines,
or between the second and third lines. From a guy-in-the-trenches
perspective, this isn't a problem; interrupting an instruction
mid-stream in order to talk about it is very bad form. Still, it's a
restriction that Damian's Separation model lacks.
> > So, if this is the case, how will a new Perl 6 user debug a program
> > failure when part of their program mysteriously disappears because
> > they just happened to have =begin at the beginning of a line?
>
> The same way they debug it when part of their program mysteriously
> disappears because they just happened to have # at the beginning of a
> line:
> Except, of course, the Pod mysteriously vanishing will be considerably
> easier to debug, because ALL lines starting with =begin vanish, whereas
> only some lines beginning with # do.
That's not really the case. The # only affects one line, and a pound in
a literal string doesn't start a comment. People grok single line
comments very well.
With the advent of block comments, this isn't as true as it used to
be. In fact, I expect that some people will have to take a moment to
wrap their heads around the notion that you ignore everything that
follows the closing bracket on the last line of the block quote. That
said, I don't expect there to be much of a learning curve here.
Still, it may be worth it to state that a line that starts with '#'
followed by a closing bracket is _not_ commented out (although said
character sequence should be stripped out of the line). Less
cognitive dissonance that way.
The start of a Pod comment now affects its line and the ones following
it.
...also not much in the way of a learning curve; in fact, I expect
that people will grok Pod Sections more readily than they will grok
block comments as currently written.
Well, easy to use Pod with other languages until they try to use the
assignment operator at the beginning of the line, or a = in a literal
string at the beginning of a line.
...or you're dealing with a language that assigns special meaning to
lines that begin with '='.
You are not going to be able to make Pod completely orthogonal to the
code that it's embedded in. You can come close (and IMHO you come
_very_ close with the Separation model that you're discussing), but
there will always be some sort of constraint placed on the code into
which you're embedding Pod.
There are other things to consider, and to me it looks like this design
decision isn't based on what's easier for the Perl 6 programmer but
what's easier for the implementors. It's not that I don't understand
both sides, I just disagree about where the complexity should be.
Thank you, Brian. That's exactly the sense that I've been getting
from the explanations being given.
Which is not to say that there isn't a time and place when ease of
implementation should trump ease of programming; taking an extreme
example, being able to write a program that consists of the single
line:
attend my every wish
is the ultimate in terms of ease of programming; it's also impossible
to implement, barring the invention of mind-reading hardware and
sapient artificial intelligence software. If a small increase in the
programmer's learning curve is the price that must be paid to achieve
a massive reduction in the implementor's workload, it may very well be
worthwhile to foist some of the complexity onto the programmer.
The question is whether or not this is one of those cases.
--
Jonathan "Dataweaver" Lang
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
On Sat, Jun 16, 2007 at 12:33:58PM +0200, Mark Overmeer wrote: > * Smylers ([EMAIL PROTECTED]) [070616 09:09]: > > > * Damian Conway ([EMAIL PROTECTED]) [070615 00:17]: > > > > * Pod 6 is both a structural and a semantic scheme; you can specify > > > > both the structure of a document, and the meaning of its various > > > > components > > > > > > Yes, and that is one of the things which worries me most *You can*. > > > It's full freedom, > > > > You're concerned that an aspect of Perl 6 might have too much freedom? > > Isn't Perl all about giving users freedom to choose their own way of > > doing something? > > Why treat documentation as a second-class citizen all the time? Why > have a standard syntax for regexes, and not for docs? Aren't you glad > that at last we get a standard for OO programming and named parameters? > The boundary between freedom and anacharchy is faint. The docs *do* have a standard syntax. I think you've been arguing for a more *specific* standard syntax and semantics. You mention OOP. For Perl 5 we have a standard, if very general, syntax and "open" semantics that have allowed people to implement OOP in a variety of ways. This was all well and good for a while until we realized that there should be some more reasonable defaults (in both syntax and semantics) for common operations in OOP. I think it's the same thing with POD6. It's "open" enough that many documentation systems can be built from it (man pages, books, magazines, wikis, etc.) For some of those documentation systems we'll have nice conventions and other conventions will grow as needed. If we find that convention isn't enough in specific areas, we'll start to grow requirements for those cases. Requirements will be enforced by the tools we use, not by the documentation specification (that way we can use the same source document for multiple purposes with different requirements). Also, I don't think that documentation is being treated as second-class at all. It's being treated as first-class but different. To form a poor analogy, imagine threads woven together to make a tapestry. The blue threads are just as important as the red threads, but they each may have different purposes in the overall design. my two cents, -Scott -- Jonathan Scott Duff <[EMAIL PROTECTED]>
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
Jonathan Lang wrote: Which is not to say that there isn't a time and place when ease of implementation should trump ease of programming; taking an extreme example, being able to write a program that consists of the single line: attend my every wish is the ultimate in terms of ease of programming; it's also impossible to implement, barring the invention of mind-reading hardware and sapient artificial intelligence software. If a small increase in the programmer's learning curve is the price that must be paid to achieve a massive reduction in the implementor's workload, it may very well be worthwhile to foist some of the complexity onto the programmer. The question is whether or not this is one of those cases. Addendum: let me note that Perl has a reputation for bending over backward to accommodate the programmer; as such, the difference in implementation workloads for the two models that Damian referenced is going to have to be _very_ severe for "ease of implementation" to win out over "ease of programming" - IMHO. Unfortunately for me, MHO doesn't count as much as DHO. "Help, help! I'm being oppressed!" -- Jonathan "Dataweaver" Lang
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
Jonathan Lang wrote: > Jonathan Lang wrote: >> Which is not to say that there isn't a time and place when ease of >> implementation should trump ease of programming; taking an extreme >> example, being able to write a program that consists of the single >> line: >> >> attend my every wish >> >> is the ultimate in terms of ease of programming; it's also impossible >> to implement, barring the invention of mind-reading hardware and >> sapient artificial intelligence software. If a small increase in the >> programmer's learning curve is the price that must be paid to achieve >> a massive reduction in the implementor's workload, it may very well be >> worthwhile to foist some of the complexity onto the programmer. >> >> The question is whether or not this is one of those cases. > > Addendum: let me note that Perl has a reputation for bending over > backward to accommodate the programmer; as such, the difference in > implementation workloads for the two models that Damian referenced is > going to have to be _very_ severe for "ease of implementation" to win > out over "ease of programming" - IMHO. Unfortunately for me, MHO > doesn't count as much as DHO. "Help, help! I'm being oppressed!" I agree, and I want to make a point for the "ease of programming" point of view. If we have any kind of references to code, the POD parser must be able to parse method/sub signatures. But since default values are allowed for optional (and iirc named) arguments, it has to parse arbitrary complex expressions anyway. Which means that a complete POD parse will likely have to fall back to STD.pm, and in that case it's ridiculous to argue about a line based parser for POD anymore - when you can parse perl 6, you can just pick the POD from the syntax tree. Moreover part of the Perl philosophy has always been to provide the best for the programmer, even if it makes implementation of the interpreter/compiler rather hard - why should we stop with this philosophy when talking about POD and POD-Parser? I'd find it very annoying to have lines starting with '=' in a heredoc beeing counted as POD. Humans don't think in terms of lines, but in terms of visual blocks (at least I do), so if everything in heredoc goes verbatim into a string, I'd expect _everything_ in that block to go into that string. Everything else looks like an artificial exception to me. -- Moritz Lenz http://moritz.faui2k3.org/ | http://perl-6.de/ signature.asc Description: OpenPGP digital signature
Re: = at Start of Line ... solution is simple
Darren Duncan wrote: Given this, there is an obvious (to me) solution for pod blocks in the middle of expressions like: my $foo = $bar; As the example shows, and I believe best practices espouse, you *indent* the code line with a leading =. I'd agree that indentation is good for readability. But I do know (and regularly use) tools that will "helpfully" strip out leading whitespace. For example, the bug tracking system I use at work drops all leading whitespace; and if you put code in MS-Word using style-sheet indentation then cut&paste will drop it. This would be unfortunate. My problems with these tools would be reduced if the POD identification rule was changed from /^=/ to /^=\w/. I.e. whitespace after the initial "=" marks it as non-pod. Dave.
Re: [svn:perl6-synopsis] r14421 - doc/trunk/design/syn
brian wrote: >> The rule you have to teach under the Separation model is: >> >> "Any line that starts with an = is Pod...and not part of your >> program." > > And that's something that now comes up very early in teaching the > assignment operator. You know, that's a benefit I hadn't even considered. Documentation *should* come up early! Thanks for pointing it out. ;-) > When we do teach the current Pod, the simple rule is that Pod starts: > >* when Perl is expecting a new statement >* there is a =something at the beginning of the line Which means that the user has to understand Perl's statement syntax and semantics, in order to write Pod. And the user also has to understand that in order to even read Pod. > Which is considerably simpler than the long rule list you used to say > the same thing (which seems a bit of FUD, honestly). Not FUD...just an partial enumeration of the full recursive complexity of the "simple rule" regarding "is expecting a new statement". > I know you think it's easier to teach and explain, but that's because > you came up with it. I hope I'm not that shallow. I would like to think I have enough experience with both design and teaching not to fall prey to that--admittedly common-- mistake. I'm heartened by the fact that several other contributors to this debate have agreed with me, but I certainly do have to acknowledge the possibility that you (as an excellent and experienced teacher) are right. Nevertheless I still believe that the new model, because it has no exceptions or context dependency, will actually be much easier to understand and to explain. > The notion that a special character in a certain column means > something was tough to explain to other people in FORTRAN too. Sure. When the "certain column" was column 6! Surely you're not arguing that: "A = in the first column introduces some documentation" is as hard to understand (or even just identify) as: "A non-blank/non-zero in column 6 continues the previous line" ??? Perceptually and cognitively, the first column is both highly distinctive and easily identified. For example, in my experience teaching Fortran (back in the mid-80s), students had no problem whatsoever learning that "A 'C' in the first column is a comment". > There are other things to consider, and to me it looks like this > design decision isn't based on what's easier for the Perl 6 programmer > but what's easier for the implementors. I assure you that that is categorically *not* the case (as I'll discuss at length in a subsequent message). Damian
Pod 6: ease of implementation vs easy of use
I'm not going to argue about the design of Pod 6 any more. As both Mark
and brian have pointed out, this really comes down to philosophical
differences that no amount of discussion is going to resolve. In any
case, I'm sure that Larry now has plenty of "grist" from which to mill a
final specification of how the Perl 6 documentation mechanism will work.
I will, however, take a moment to answer the accusation that I appear to
have redesigned Pod the way I did in order to make implementation
easier...and at the expense of making life harder for programmers and
educators.
It's hard to believe anyone could think I would ever do that. It's
almost as if the they don't know me at all.
From the very first day I became part of the Perl community (August 18,
1998, when I presented Getopt::Declare and Lingua::EN::Inflect at the
Second Perl Conference), my entire philosophy and purpose has been to
make things *easier* for users of Perl, no matter what that did to the
complexity of the implementation.
Every serious module I've ever written over the subsequent decade has
had that same characteristic and intended function: Attribute::Handlers,
Class::Contract, Class::Multimethods, Class::Std, Config::Std,
Contextual::Return, Filter::Simple, Getopt::Euclid, IO::Prompt,
Module::Starter, NEXT, Parse::RecDescent, Regexp::Common,
Smart::Comments, Switch, Text::Autoformat...etc., etc.
Indeed the term "a Damian module" is now widely used to mean "software
that makes your life easier...until you actually try to read the source
or understand the implementation". :-)
I've always been quite proud of that...since that description is pretty
much the definition of the perl interpreter itself. I always felt that
meant I was doing my job right.
I've also lectured and taught academic and professional classes on
interface design for several decades now, and always with that same
basic message: make life easier for the user, no matter how much that
complicates the implementor's job.
Certainly, anyone who has sat in on a Perl 6 design meeting will tell
you that I've consistently argued that way; frequently to the point of
aggravating those courageous souls who are charged with the task of
implementing Perl 6.
So it actually *hurts* me that people might think I would ever
compromise on usability, just to facilitate implementability. Please
read what I wrote again. I *did* claim that "easier to implement" was a
nice side-benefit of my design...but only because I was directly
responding to brian's question about Pod 6's adaptability to other
programming languages.
I *never* said ease-of-implementation was a major consideration, of a
motivation for, or even a significant argument in favour of, the
original design. My entire argument for separated Pod is based on
promoting the prominence and readability of Pod documentation by
distinguishing it lexically, rather than syntactically.
Enough. I will now get back to designing the new A<> formatting code
('A' for *A*lias to *A*mbient *A*rtifact), which I'll preview early
next week. Though I'm sure people won't like that new feature either,
since it's going to be designed using the same "separated model"
philosophy. ;-)
Damian
Re: Quirky comments
I have a problem with both extremes, and I want to solve it with a dose of postmodern apathy. It may seem a bit insane, but I think that in print qq:to/END/ =for whatever END I would prefer that the =for is considered Pod by any standard Pod parser, but is *not* considered Pod by the Perl 6 parser. And I think that's just fine. If the programmer really wants to put Pod in a string, they can just be responsible for stripping it out themselves. And a standard Pod parser shouldn't be expected to parse full-up Perl. If an accidental directive shows up in a quoted string and causes problems to the Pod parser, then it can be fixed, say by indenting a here doc. But I expect this to be quite rare in practice. I picked the initial = for Pod in the first place because most languages don't ever have that character at the start of a line. I don't believe it's worth complexifying the quote parsing with additional escapes that many folks will consider surprising, and it's *certainly* not worth installing a preprocessing pass over the text. We've been working very hard to keep the Perl parser a fairly simple one-pass parser. Let's not blow it now. In short, trying to make Pod and Perl 6 view a document identically in every case is not worth the cost, in my estimation. Larry
Re: = at Start of Line ... solution is simple
On Sat, Jun 16, 2007 at 02:22:55PM -0700, Dave Whipp wrote: : My problems with these tools would be reduced if the POD identification : rule was changed from /^=/ to /^=\w/. I.e. whitespace after the initial : "=" marks it as non-pod. S26 says that ^^ '=' \s is for continuing a previous directive, and therefore *must* not be interpreted as a new directive, so I think you pretty much already have your wish, if we assume that a missing previous directive implies that a "spaced" = isn't extending anything. This interpretation would certainly cut down false matches way down in any culture that conventionally puts spaces on both sides of an = when used for assignment. (And if there isn't a space after, there isn't likely to be a space before that would get wrapped.) Larry
Re: Quirky comments
Larry Wall wrote: I have a problem with both extremes, and I want to solve it with a dose of postmodern apathy. It may seem a bit insane, but I think that in print qq:to/END/ =for whatever END I would prefer that the =for is considered Pod by any standard Pod parser, but is *not* considered Pod by the Perl 6 parser. And I think that's just fine. If the programmer really wants to put Pod in a string, they can just be responsible for stripping it out themselves. And a standard Pod parser shouldn't be expected to parse full-up Perl. Summary: Perl treats quoted Pod as quoted text, and all other Pod as comments; Pod treats all Pod as Pod. Effects: 1. You trade the brutally surprising behavior of whole lines of string literal content vanishing for the much more subtle surprising behavior of whole lines of string literal content being available via $=pod variables (some might consider the latter to be a feature). 2. Pod Sections behave just like block comments (aside from the pod variables thing), which is very nice. 3. There will be a few rare cases where the Perl programmer will need to cheat to keep something that looks like Pod from registering as Pod; this will be easy enough to do when it's needed. Opinion: That's a significant trade up, and addresses my biggest concerns. -- The only other thing that I'll continue to lobby for is that the line starting with a block comment's termination tag should _not_ be considered part of the comment, save for the termination tag itself. Programmers are likely to be surprised when text that follows a closing bracket is treated as being included within it. -- Jonathan "Dataweaver" Lang
Re: Quirky comments
On Sat, Jun 16, 2007 at 08:45:21PM -0700, Jonathan Lang wrote:
: The only other thing that I'll continue to lobby for is that the line
: starting with a block comment's termination tag should _not_ be
: considered part of the comment, save for the termination tag itself.
: Programmers are likely to be surprised when text that follows a
: closing bracket is treated as being included within it.
I don't think so. Consider:
#(
# 1,
# 2,
# 3,
#).sort.say
Translating that to $_.sort.say is going to elicit Great Astonishment.
And by and large, line-endiness doesn't matter for #} because people
generally put } on a line by itself anyway. And when the #} is
*unexpected* it almost certainly means they meant it as a line-end
comment:
#for @foo {
# .say
#}; exit();
Finally, if the user really wants to terminate a comment after }, all they
have to do is just make sure the opening #{ isn't first thing on a line.
And then it's even symmetrical in a sense, going from mid-line to mid-line.
Larry
