I fully agree with David's response to this mail. The only
thing I would like to add:
* Smylers ([EMAIL PROTECTED]) [070621 18:02]:
[*0] Consider a function Cvalid_postcode. I'd document it along
the lines of:
valid_postcode
Returns whether the specified postcode is
Mark Overmeer wrote:
Then, when you want to add some docs to the method, to help the
correct use, add it, for instance like:
method isValidPostalCode(str $postalcode) returns bool {...}
` Check wether the postal code confirms to the standards
`$postalcode: a string with blanks
* Moritz Lenz ([EMAIL PROTECTED]) [070622 09:16]:
Damian Conway wrote:
Would the following syntax suffice?
method isValidPostalCode(str $postalcode) returns bool {...}
=PURPOSE Check weather the postal code confirms to the standards
=ARG $postalcode
a string with
* Damian Conway ([EMAIL PROTECTED]) [070622 09:02]:
Mark Overmeer wrote:
Then, when you want to add some docs to the method, to help the
correct use, add it, for instance like:
method isValidPostalCode(str $postalcode) returns bool {...}
` Check wether the postal code confirms to the
Mark Overmeer wrote:
Then, when you want to add some docs to the method, to help the
correct use, add it, for instance like:
method isValidPostalCode(str $postalcode) returns bool {...}
` Check wether the postal code confirms to the standards
* Damian Conway ([EMAIL
Mark Overmeer wrote:
* Damian Conway ([EMAIL PROTECTED]) [070622 09:02]:
Mark Overmeer wrote:
Then, when you want to add some docs to the method, to help the
correct use, add it, for instance like:
method isValidPostalCode(str $postalcode) returns bool {...}
` Check wether the
On 6/22/07, Mark Overmeer [EMAIL PROTECTED] wrote:
snip
* Jonathan Lang ([EMAIL PROTECTED]) [070622 10:41]:
snip
Please forgive my ignorance: what does AST stand for?
The Abstract Syntax Tree, the result of the code parser, un-interpreted.
snip
You mean it isn't Andrew S. Tanenbaum? Well,
On 6/22/07, Smylers wrote:
David Green writes:
Well, clutter like Blah: none seems to me to be more the fault of
the doc-formatter for not hiding lines like that.
It's more the repetition in the lines you snipped that I really object to:
Ah. (That was sneaky of me.) I agree with that --
Mark Overmeer writes:
* Smylers ([EMAIL PROTECTED]) [070616 09:09]:
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
brian d foy writes:
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
On 6/21/07, Smylers wrote:
Mark Overmeer writes:
The boundary between freedom and anacharchy is faint.
Indeed. And I'd much rather we err on the side of anarchy.
I'd much rather we didn't err at all! Just because something isn't
perfect doesn't mean it's an error, or that it's not worth
In article
[EMAIL PROTECTED], Chaddaï
Fouché [EMAIL PROTECTED] wrote:
The Learning Perl 6 argument seems
equally contrived to me since anyway you don't need POD to understand
programming in Perl and I never actually learned POD until I wanted to
do a real module and document my little console
I'm quite surprised by this debate... To me it seems a clear rule that
state that if a line begin with = then it starts a POD section is
way easier to understand than a line beginning by = will start a POD
section except if it is in a Perl statement, or in a :to section, or
in a string literal,
* Jonathan Scott Duff ([EMAIL PROTECTED]) [070616 20:15]:
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
In article [EMAIL PROTECTED], Damian Conway
[EMAIL PROTECTED] wrote:
[writing publicly to head off any notions there's a personality problem
here]
brian wrote:
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
brian wrote:
[writing publicly to head off any notions there's a personality problem
here]
I said I wasn't going to continue this discussion, and I'm not. But I
do want to agree publicly that there's no clash between brian and
myself. I have only the highest respect for brian: as a person, as
In article [EMAIL PROTECTED], brian d foy
[EMAIL PROTECTED] wrote:
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.
My comment here was offensive to Damian (and
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
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
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
* 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
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
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
* 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
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.
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
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
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
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
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
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
* Damian Conway ([EMAIL PROTECTED]) [070615 00:17]:
Larry and Thom have each ably explained the rhyme and reason of the choices
that we made for Pod 6. Here I will merely summarize those reasons, and
answer a specific question.
* Pod and Perl (or any other ambient source code) are to be
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.
* Damian Conway ([EMAIL PROTECTED]) [070613 22:46]:
My underlying model is that documentation and the source it's documenting
should be entirely orthogonal. So, to me, it would be very surprising if a
programming construct (block comments) interacted with documentation. Or
vice versa.
Mark Overmeer wrote:
We had a private discussion about this already three years ago: I
fully disagree! If the code and the documentation are not entangled,
why do you want to put them in the same file? Why do you put them in
the same distribution even?
No, the documentation is all about
I'm going to stay away from the POD referencing Perl debate for the
time being. Instead, a couple of thoughts:
1. It has always been my understanding that comments intimately relate
to documentation, despite being part of Perl's syntax. As such, they
are a technical violation of this
On 6/14/07, Mark Overmeer [EMAIL PROTECTED] wrote:
I had suggested syntax like this, in Perl6:
class Mail::Message {
`base class for message types
.has $msgid;
`The (internet wide) unique string which identifies this
`message object. May be undef as long as the
Jonathan Lang wrote:
2. Getting block comments to hide POD blocks wouldn't require the POD
parser to have a full implementation of a Perl parser. It would
require the POD parser to have a _limited_ implementation of a Perl
parser, one that's capable of identifying block comments. And IIRC,
On Thu, Jun 14, 2007 at 09:20:51AM -0600, Thom Boyer wrote:
: Compare that with the simplicity that $larry $damian are promoting.
Yes, and the simplicity we're promoting here is mostly *syntactic*
simplicity. It's obvious that at a semantic level, there has to be a
certain amount of incest
Larry Wall wrote:
So I think a named reference is a good compromise, where the name in
the documentation (in some easily recognized syntactic form) refers
to the next declaration (or set of declarations) of that same name.
Hopefully the pod either knows implicitly or has been told explicitly
how
Larry and Thom have each ably explained the rhyme and reason of the choices
that we made for Pod 6. Here I will merely summarize those reasons, and answer
a specific question.
* Pod and Perl (or any other ambient source code) are to be syntactically
separated, even when there are semantic
say :to(END);
=begin POD
blah blah blah
=end POD
END
If I understand matters correctly, the POD code in the above example
isn't POD code at all, but rather the content of a multi-line quote.
No. It's Pod. *Any* line that begins with '=begin' always starts a Pod
block. Always.
To get
On 6/14/07, Damian Conway [EMAIL PROTECTED] wrote:
snip
To get the multi-line quote, you'd need:
say :to(END);
=begin POD
blah blah blah
=end POD
END
Damian
Would this work as well?
say :to(END);
\x{3D}begin POD
blah blah blah
\x{3D}end POD
END
Chas Owens asked:
Would this work as well?
say :to(END);
\x{3D}begin POD
blah blah blah
\x{3D}end POD
END
Yes, except for the :to actually needing to be qq:to (which was wrong
all the way through these examples, BTW).
You could also just use:
say qq:to(END);
\=begin POD
blah blah blah
On Fri, Jun 15, 2007 at 11:59:49AM +1000, Damian Conway wrote:
: Chas Owens asked:
:
: Would this work as well?
:
: say :to(END);
: \x{3D}begin POD
: blah blah blah
: \x{3D}end POD
: END
:
:
: Yes, except for the :to actually needing to be qq:to (which was wrong
: all the way through these
Author: larry
Date: Wed Jun 13 13:55:24 2007
New Revision: 14421
Modified:
doc/trunk/design/syn/S02.pod
Log:
Block comments should not hide POD, pointed out by TheDamian++
Modified: doc/trunk/design/syn/S02.pod
==
[EMAIL PROTECTED] wrote:
+Block comments may be nested within other block comments (with the
+same or differing brackets). POD comments may also be nested within
+block comments. (These are still visible to the POD parser; if you
+wish to comment out a block of mixed POD and Perl 6 code,
Jonathan Lang asked:
What's the rationale for keeping POD comments that are nested in block
comments visible to the POD parser?
The rationale is that Perl 6 and Pod 6 have been designed to be completely
independent and uncoupled. That way, you can look at a piece of Pod without
worrying
48 matches
Mail list logo
