* Smylers ([EMAIL PROTECTED]) [070621 20:33]:
Documentation, unlike code, doesn't have to be backwards compatible: if
Perl 6.0.1 changes the API of a standard function that will break
existing code; but if Perl 6.0.1 has documentation with a different
structure from Perl 6.0.0, that won't
Juerd wrote:
This dedicated OO documentation must be core, because Perl itself is
heavily OO.
* Damian Conway ([EMAIL PROTECTED]) [070621 23:54]:
Yes. I completely agree that such a tool not be standard and universally
Do you mean must be i.s.o. not be?
available. Just as the
* Damian Conway ([EMAIL PROTECTED]) [070622 08:38]:
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
Mark Overmeer wrote:
IMO, POD6 should not provide the possibility to build such tools: it
should *be* the tool. With a nice (compact) standard definition how
to document each of the designed features in Perl6
And this is a succinct statement of one half of our fundamental philosophical
In article [EMAIL PROTECTED], Smylers
[EMAIL PROTECTED] wrote:
Juerd Waalboer writes:
Smylers skribis 2007-06-21 21:33 (+0100):
I disagree. perldoc.perl.org was started by JJ, gained popularity,
and then got awarded the official blessing of the onion. Over the
years there have
OK. After much thinking on the subject, here are my recommendations:
First: give Pod the ability to delimit blocks of ambient text, e.g.:
=text
class Foo {
has $bar;
}
=stop
'=text' and '=stop' would be considered to be separate but related
single-line Pod Sections, so Pod-stripping
Mark Overmeer wrote:
[...yet another honest and heartfelt plea for Pod 6 to be something
entirely different from what it is currently designed to be.]
The solution is simple, you know, Mark. Why not just write up your own
alternate S26, redesigning Pod 6 the way you think it should work, and
In article
[EMAIL PROTECTED], Damian
Conway [EMAIL PROTECTED] wrote:
Mark Overmeer wrote:
[...yet another honest and heartfelt plea for Pod 6 to be something
entirely different from what it is currently designed to be.]
The solution is simple, you know, Mark. Why not just write up your
The outcome is that poddoc can be Pod6 pure and perldoc can be (as its
name suggests) documentation for Perl.
I failed to mention that it also has the benefit that developers can read the
perldoc if they care about method details - or they could read poddoc if they
only want a 7000 ft view
The outcome is that poddoc can be Pod6 pure and perldoc can be (as its
name suggests) documentation for Perl.
Sorry to reply to myself twice.
Making poddoc independent of Perl 6 opens the doors a little further for
having pythondoc and phpdoc and yourlanguageheredoc which extract the POD
Damian Conway writes:
Here's the first draft (documented in Pod 6, of course ;-).
Feedback and suggestions are most welcome.
Note that C=alias is a fundamental Perldoc directive, like C=begin
or C=for; it is Inot an instance of an
Labbreviated block|#Abbreviated blocks. Hence there is no
Smylers reported:
I was with you right up until the mention of C=encoding; what's that
got to do with anything?
CP bug. Patched. Thanks!
Damian
Damian Conway writes:
Here's the first draft (documented in Pod 6, of course ;-).
=head3 Ambient aliases
The CA formatting code specifies an Balias to an ambient
antecedent.
Please can you explain the reasoning for choosing antecedent, rather
than successor?
I'm not disagreeing with
Juerd Waalboer writes:
Damian Conway skribis 2007-06-21 11:45 (+1000):
A dedicated OO documentation tool could certainly do a better job in
that case, I heartily agree. I'm looking forward to using one.
This dedicated OO documentation must be core, because Perl itself is
heavily OO.
Smylers skribis 2007-06-21 21:33 (+0100):
That doesn't follow.
It's an opinion.
I disagree. perldoc.perl.org was started by JJ, gained popularity, and
then got awarded the official blessing of the onion. Over the years
there have many several sites with Perl documenation.
That's not a way
Juerd Waalboer writes:
Smylers skribis 2007-06-21 21:33 (+0100):
I disagree. perldoc.perl.org was started by JJ, gained popularity,
and then got awarded the official blessing of the onion. Over the
years there have many several sites with Perl documenation.
That's not a way of
Juerd wrote:
Damian Conway skribis 2007-06-21 11:45 (+1000):
A dedicated OO documentation tool could certainly do a better job in that
case, I heartily agree. I'm looking forward to using one.
This dedicated OO documentation must be core, because Perl itself is
heavily OO.
Yes. I
brian asked:
Couldn't most of this be figured out by making Pod6 extensible (or
whatever the right term is). Pod6 would be more of the syntax and basic
operation, but other people could have custom directives that their
Pod6 translators and formatters could then use. That is, not all of
this
* Damian Conway ([EMAIL PROTECTED]) [070620 05:17]:
Feedback and suggestions are most welcome.
Clear and usable, in the boundaries you set to yourself.
Just my thoughts. A lot of questions and speculation, you do
not need to answer all. I'll try to only comment on this design,
and not restart
19 matches
Mail list logo
