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
