* 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 syntactically
> separated, even when there are semantic interconnections
Why? Who says that?
> * Perl 6 will be able to access ambient Pod via $=POD (and other
> $=WHATEVER variables)
Cannot find anything about that in S26
> *
> *
> * That does not, however, mean that source code and explicit mark-up are
> (or should be) either equivalent or syntactically commingled
Of course: both serve a different purpose. That's why I would like to
avoid replicating code information in the docs which I have to write: I do
not want to write the attribute names again, and so on. [my impression is
that I use this argument exactly in the opposite direction as you intent]
The code tells how to do it, the docs describe how to use it, the comments
explain how it works. And on some places these tasks overlap. Then, you
have the choice either to write the same thing twice, or (define a
syntax to) share.
> *
> * This will be possible in Perl 6, since both the Pod and Perl 6 parsers
> will be accessible from Perl 6.
And we can access internet as well. But that doesn't say much, does it?
> *
> * 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, like XML, and without a convention everyone may
think-up there own way of documenting the same kinds of code elements.
Ever tried to merge two aged databases with personnel information?
It's the same horror.
Of course, programmers get all the freedom of the world (the already had)
but we need POD6 only to document Perl6. That is a limited task. Some
people use POD to write books, but is that a reason to give everyone these
features? What is the purpose to people this power (and the challenge
to use it) when there is such a limited set of things to document?
> * Such tools would (usually) convert the information extracted from
> [source + semantic-Pod] into purely structural Pod, which could then
> be fed to any suitable pod-to-whatever converter
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.
> * In other words, the tool-chain envisaged is something like:
>
> perl6doc pod2whatever
>
> source
> + purely
> structural Pod -------> structural -----------> plaintext
> + Pod \----------> HTML
> semantic Pod \---------> XML
> \--------> roff
> \-------> MPEG
> \etc.
^^^^^^^^^^^^ can/will be different *per module*
A structure which is very well known, for instance from LaTex,
looks like this:
perl6doc pod2whatever
source doc
+ -------> tree --------------> plaintext
structural Pod ^ \----------> HTML
| \---------> XML
semantic \--------> roff
definition \-------> MPEG
|
style sheets ---'
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.
The actual formatting is only at the back-end, which knows what
the back-end is capable of. So search.cpan.org can design a
nice CSS. Websites have really improved since CSS: finally all
the pages within a website look the same.
And what I would like to see is that doc-tree and Perl6 AST are one.
Producing docs then can be done via standard introspection.
> * Which means that Pod 6 needs to be a suitable pure-structural-mark-up
> target language with an extensible semantic overlayer
> * Which is precisely what it has already been designed to be
With your structure, yes.
> * 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.
> - Then generate unified documentation by extracting information from
> wherever its available (source or mark-up), according to what the
> reader asks for
The semantics differ per module, so the reader cannot (for instance)
use her own style sheet: the superset of definitions is not known.
> - The issue is not having sufficiently powerful Pod syntax;
> the issue is having sufficiently powerful documentation-generating
> *tools*
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]
> To answer Mark's specific question:
>
> > 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 message is
> > `begin composed.
> >
> > .has $content_type = 'text/plain';
> > }
> >
> > Damian, can you show how you would document the same code in POD6
> > syntax to get a comparible short man-page?
>
> 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.
So: you need at least a few lines more in above counter-example
to make this work.
- the semantic pod
- in the purely structural pod
- in pod2whatever
more?
In my "vision", the example is complete. Everything else is determined
by the processing tools and style sheets.
> PS: I agree that there needs to be a mechanism for abstracting names
> within Pod and for extracting those names from ambient code. I will
> propose such a mechanism and the syntax for it in a subsequent email
> (probably early next week).
I am looking forward to it.
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. And I feel
that its freedom makes my life as programmer any easier.
[ 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 ]
--
Regards,
MarkOv
------------------------------------------------------------------------
Mark Overmeer MSc MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
