Mark Overmeer wrote:
You may remember that I repeatedly asked @Larry not to forget the
documentation aspect in the redesign of Perl, in person during various
YAPCs and Workshops. Then, when you finally took the challenge, I have
send you a extensive email showing various alternative syntaxes for
condensed, integrated documentation strategies. (2 nov 2005)
Yes. You did all that. I was extremely grateful for that input. And I took it
(and many other's people's feedback) and created the current design...in such
a way--I believe--that you *will* be able to easily and extensibly use the new
Pod and Perl parsers to implement such integrated documentation strategies.
I have already proven that adding some simple logical markup to the POD(5)
syntax can simplify the documentation process enormously, with my OODoc
(::Parser::Markov).
Agreed. And I made sure that Pod 6 could be easily extended with such markup.
Moreover I added in the concept of "semantic blocks", which directly mirror
many of your MARKOV language notations, often right down to the actual names
chosen (albeit in capitalized form).
As I already reported in one of the initial messages
of this (long) thread, the tool saved me to type 700.000 characters of
(needed dupplicated) text for my MailBox suite alone. That was a simple
gain within the classical POD dogma; with real integration, we can
reduce our documentation efforts much further.
[Shall I give a lightning talk on OODoc in action, at upcoming YAPC::EU?]
By all means. But not for my sake. I have already studied and understood your
tool and the advantages it provides for certain types of documentation tasks.
That's why I designed Pod 6 specifically to support such tools.
After all, Larry's track record is clear: he's never once allowed
someone's reputation or status (even his own!) to deter him from
replacing an existing design with someone else's superior one.
True. However, when the common @Larry believe is that POD6 should build
on POD(5) ideas of orthodox orthogonalism, then it is a waste of my
sparse time. I am not afraid to take such challange, opposit of that:
otherwise this discussion probably had died out days ago. But I do have
a number of large Perl(5) projects on my hands already.
Understood. But you keep saying we're not giving you what you want, without
showing us specific examples of what it is you want that we're not giving you.
What else can we do but ask you to provide specifications for the pieces you
think are missing?
And, no, I don't consider the pointers to your excellent module to be suitable
specific examples of what we're not giving you...mainly because I believe that
the Pod 6 documentation language I've designed (in conjunction with the
ability for Perl 6 to parse Perl 6) *does* give you what you need to build
such tools.
So it seems we're still at an impasse. I fully respect your decision not to
attempt a full alternative design (if anything, your estimate of it only
taking "weeks" is optimistic ;-), but unless someone is willing to step up and
suggest some specific improvements to the current proposal, how can we move
forward towards the best possible result?
Damian
