* 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
Moritz Lenz:
=begin pod
=head3 Cmethod from_string(Str $s);
[..]
=end pod
method from_string(Str $s){
# implementation of that method here
}
Since method signatures are very expressive in Perl 6, there should be a
way of accessing them in the POD without copy paste.
As I
* Thomas Wittek ([EMAIL PROTECTED]) [070614 15:18]:
So maybe directives like method, sub, attribute, class etc. might be a
better choice regarding semantics.
See OODoc::Parser::Markov
It's a bit like HTML-XML, where the former lacks most of the semantics
and makes the information processing
Thomas Wittek skribis 2007-06-14 17:18 (+0200):
So maybe directives like method, sub, attribute, class etc. might be a
better choice regarding semantics.
Yes, a better choice indeed. But I would still not be happy with it,
because there would still be a lot of code duplication.
method foo
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
On 6/14/07, Thomas Wittek [EMAIL PROTECTED] wrote:
It's a bit like HTML-XML, where the former lacks most of the semantics
and makes the information processing - not to speak about a consistent
look over several documents - a lot harder.
Actually, that's incorrect. HTML is a markup language
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,
Mark Overmeer schreef:
The nicest thing would be that the semantic docs become part of the
parse tree, which then (using standard introspection) can be used to
generate manual pages, natively into POD, roff, HTML, whatever.
I like to call them: lexical comments.
--
Groet, Ruud
Thomas Wittek wrote:
I mean POD uses constructs like headlines, lists, blocks, italic etc.
which all describe _how it looks like_ and not _what it is_.
I think Damian would take exception to that statement. He worked quite
hard to make sure that POD describes _meaning_ rather than
Thomas Wittek wrote:
Moritz Lenz:
=begin pod
=head3 Cmethod from_string(Str $s);
[..]
=end pod
method from_string(Str $s){
# implementation of that method here
}
Since method signatures are very expressive in Perl 6, there should be a
way of accessing them in the POD without
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
It's a valid aside to note that, while people know what singular and
plural are, few people use or even refer much to the Greek use of a
special intermediary (the dual) when there were exectly two of
something...but the basic mindest of dichotomy is a fundament of the
language. (c.f. the men/de
* 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?
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
21 matches
Mail list logo
