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 can*.
> It's full freedom,

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?

> like XML, and without a convention everyone may think-up there own way
> of documenting the same kinds of code elements.

Yes.  But in reality many people will follow what others do, or look to
follow best practices.  With Perl 5 you have complete freedom as to the
names of C<=head1> sections in the Pod for modules, yet in browsing Cpan
it's clear that there are conventions and many people use the same
headings.  So not mandating a convention isn't much of a problem.

Moreover, I reckon that not mandating a convention is essential.  Look
at what's being done with Perl 5 at the moment (not specifically Pod,
just in the Perl 5 community in general) and the best practices that
have sprung up in recent years (and are still evolving).  People are, of
their own accord, following conventions that nobody had even thought of
at the time Perl 5 was released; even at the time Perl 5.6, say, was

> In this structure, the responsibility of how things get interpreted is
> not for the programmer, so consistent over all modules.  We can make
> and manual-pages with a consistent structure.

Do you really think that people can now, before Perl 6 has gained
anything approaching the usage we expect, make policy for how things
should be documented, such that that policy will be the best possible
way of documenting everything written in Perl 6, for ever?  Or even a
good way?

That strikes me as incredibly shortsighted, verging on arrogance by
whoever comes up with the rules, and doomed to failure.

Rather than trying to map out the future in detail (which is tricky),
the best we can do is come up with things that are sufficiently flexible
that they're capable of being used in ways we haven't yet thought of.

Then when somebody, years from now, has a good idea, it will be possible
for that to be implemented (and followed by others), rather than tying
us to some convention set at an arbitrary point in the past.

> > * 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.

Yes, but on the other side of the argument coconuts and fax machines are
not integrated.  I'm reasonably confident that for every pair of things
which you list as being integrated I can come up with a pair which
aren't; I doubt that will really assist the argument one way or t'other.

> the issue is to have sufficiently integrety in code and markup
> to be able to create documentation-generating tools which produce enough
> quality.

Damian's spec permits this.

> And at the same time give the programmer the mimimal burden on writing
> documentation, to increase the chance that it is present and good.

You should 'Perl 6 Documentation Best Practices', with guidelines for
how to use Pod.  I'm sure many people would appreciate just being able
to follow a template rather than having to make decisions over the small
details of what to do.

That way we have a convention for those that want it, but also don't tie
ourselves into anything.

If a particular convention gains widespread approval then peer pressure
should encourage its use (in the same way that strict and warnings are
currently optional in Perl 5, but in the absence of a good reason it's
expected that they be used).


Reply via email to