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 citizen all the time?
I'm not suggesting we do; it's precisely _because_ Perl provides so much
freedom in things like coding style that I think it would be bizarre to
be so restrictive in the documenation format. Documentation should be a
first-class citizen, and therefore have as much freedom as coding.
> Why have a standard syntax for regexes, and not for docs?
We have a standard _syntax_ for docs; what you are additionally
proposing are standard _semantics_, which is something regeps (and other
areas of Perl) don't enforce -- they just provide the tools for
programmers to use them as they wish.
> Aren't you glad that at last we get a standard for OO programming and
> named parameters?
Yes. But I'm also glad that these have both carefully been done in ways
which don't enforce them, leaving programmers free to do things in other
ways.
> The boundary between freedom and anacharchy is faint.
Indeed. And I'd much rather we err on the side of anarchy. Many times
have I been frustrated by the limits of some software or programming
language. Far better to allow somebody enough freedom to create a poor
piece of software (since that's going to be possible anyway) than to go
too far in t'other direction and inadvertently prevent somebody in the
future from doing something really clever that none of us have yet
thought of.
> > 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.
>
> Well, the you are talking about the top three headers, the most.
Not true; there are several more which are shared between Cpan
distributions (by different authors).
> And those have a good example in standard UNIX manual-pages. So:
> there is a definitions for them, which most people have seen.
I am sceptical of your claim that most Cpan authors have seen any
official definitions of sections in Unix manual pages.
> > 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?
>
> There is no need to think that a documentation syntax develops
> differently than a programming language.
I agree. And programming languages develop in hard-to-predict ways,
which is why Larry is putting lots of flexibility for things to be
redefined into Perl 6, so it can grow and adapt in line with future
developments. It would be good if Pod can keep up.
> So when Perl is developing, POD can develop in parallel.
Exactly!
> > That strikes me as incredibly shortsighted, verging on arrogance by
> > whoever comes up with the rules, and doomed to failure.
>
> Sorry? Not only you insult me,
Apologies, that wasn't supposed to be an insult. Note that it isn't
that I'm objecting to your rules (nor any particular rules), nor
doubting your abilities to come up with good rules; you'd be one of the
best people for coming up with some standards. I just don't believe
that _anybody_ can come up with rules that won't be bettered at some
point in the future.
> but you also ignore all these other languages which do have a nice and
> standard way of documenting. Insignificant languages, like Java,
> which we tend to ignore.
I've encountered Javadoc, and I really dislike it[*0]. The fact that a
standard exists does not make it a good one.
Smylers
[*0] Consider a function C<valid_postcode>. I'd document it along
the lines of:
valid_postcode
Returns whether the specified postcode is valid, for example:
if (valid_postcode $postcode) {
Javadoc-style systems seem to insist on documentation like:
valid_postcode
Description: Returns whether the specified postcode is valid.
Parameters:
$postcode: (string) The postcode to test for validity
Returns: (boolean) Whether $postcode is valid
Exceptions: none
Side Effects: none
Lots of structure and consistency, but in practical terms no
additional information compared to my informal doc -- and the
verbosity and repetition actually make it harder to spot the
information you want.
