* Jonathan Scott Duff ([EMAIL PROTECTED]) [070616 20:15]:
> You mention OOP.  For Perl 5 we have a standard, if very general,
> syntax and "open" semantics that have allowed people to implement OOP
> in a variety of ways.  This was all well and good for a while until we
> realized that there should be some more reasonable defaults (in both
> syntax and semantics) for common operations in OOP.

OOP in Perl5 has a mechanism, but not a standard in the use of those
features.  Full OO languages all choose a direction, but there are
serious culture differences.  Perl uses them all.  There are many ways
how to instantiate an object, which is lot of fun as programmer but a
hassle for "the average" programmer.  Within one program, you may very
well need to use different instantiation techniques...  Of course, this
could have been forseen (perl is not the first language which implements
OO), and some advice on the convention to use could have avoided wild
collection of approaches we see now.

This is also why "Perl Best Practices" is a good book [shameless plug]
although I would have welcomed it 11 years earlier.

> I think it's the same thing with POD6. It's "open" enough that many
> documentation systems can be built from it (man pages, books, magazines,
> wikis, etc.) For some of those documentation systems we'll have nice
> conventions and other conventions will grow as needed. If we find that
> convention isn't enough in specific areas, ...

Without any doubt, there are thousands of documentation systems around.
At least ten percent of them are considered "the best ever made" by
its developer or developer community.  Just by simple math, the chance
that the system developed really is the best is less than one percent.

Gladly, there are many areas of application for documentation systems,
and there is a large variety in taste by the users.  So per user/usage,
a different doc-system can be the best.  Still, its a muddy terrain.

POD6 has the unique opportunity to become "the best documentation system"
for a specific large group of users: Perl programmers.  Tenth of thousands
of people will use POD6 in their Perl6 programs, every day.

IMO, any argument that POD6 is good because it can be used to write books
or express complex mathematical expressions is really frightning me.
Damian is correctly avoiding this, in his argument.  Is this another area
where our community is trying to incorporate every thinkable feature in
some design?  And in the process, producing such a complex design that
it deserves an extra volume in "Programming Perl 6"? (Next to the 1000
page volumes for each of basic syntax, grammars, and OO).

IMO, the needs for POD6 are much simpler: a way to document the features
of the related Perl6 code, and smooth that into (parts of) manual pages.
If you write a book, than use pod6-to-docbook or pod6-to-pod, or whatever,
to get some fragments in your some documentation system which is
specialized in books.

Every single complication added to the doc syntax will make it not
to understand for a large percentage of the primar target community,
as every teacher can tell you from experience.

> Also, I don't think that documentation is being treated as
> second-class at all.  It's being treated as first-class but different.

It's treated second-class in the Perl6 sense: the tools are not an
integral part of the Perl6 environemnt.

When I create a program, it starts with a goal.  To reach that goal,
I have to write some code, some docs, some tests.  For me, it is all
part of the program.  I do not see one to be of more importance than
the other: all three are first-class sitizens in my program.   And what
I really wish for is that those three work together in een KISS way;
to achieve my goal in no time so I can drink (more) beer.  Yeh, on the
subject of tests,... :-b

       Mark Overmeer MSc                                MARKOV Solutions
       [EMAIL PROTECTED]                          [EMAIL PROTECTED]
http://Mark.Overmeer.net                   http://solutions.overmeer.net

Reply via email to