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 --
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? W
Damian Conway wrote:
> You gave the hint that comments are also in the parse tree.
They can be. Better still, the (raw) Pod can also be kept in the parse
tree...since, like comments, the Perl parser still has to recognize it, even
when it's focusing on extracting Perl.
...And since the Perl p
Mark Overmeer 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 blanks trimmed.
>>=RETURN
>>the stri
> >> 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
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 wethe
* 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
* 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 confi
Damian Conway wrote:
> Mark Overmeer 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 blanks trimmed.
> =RETUR
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: given the function's name, the name(s) of its parameter(s), and the
short descri
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 trimm
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 C. I'd document it along
> the lines of:
>
> valid_postcode
>
> Returns whether the specified postcode is valid, for ex
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
Chaddaï Fouché writes:
> 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
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 Po
Mark Overmeer writes:
> * 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
> >
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 citize
Mark Overmeer writes:
> * 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. That
> > permits Pod to be used to document just about anything; all you need
> > to allow
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 littl
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 litera
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
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]>, 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 shal
* 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
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 ev
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
>>
>> i
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 programm
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 me
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
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 kn
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.
* 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
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 th
> 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
* 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 o
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 mo
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
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 anyth
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
* 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
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 the
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
\=en
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
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 ge
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 interc
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
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 betw
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 IIR
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
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 "separat
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 a
* 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.
>
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 abou
[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, either
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
==
--
55 matches
Mail list logo
