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 uti
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
> > >
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
differ
* 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 abilit
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 fo
* Damian Conway ([EMAIL PROTECTED]) [070621 08:07]:
> 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,
Mark Overmeer sought to clarify:
* 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"?
Oops. Indeed. Can't even claim it must have been a Freudian slip, since I
really *do* believe
> 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 p
* 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 b
Hi Larry.
You wrote:
: Please can you explain the reasoning for choosing antecedent, rather
: than successor?
I think having to pick either one or the other is likely a design smell.
Maybe it would be better to have predeclared extractors than to have a
search strategy baked half-heartedly int
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 has
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 completel
On 6/21/07, Smylers wrote:
Please can you explain the reasoning for choosing antecedent, rather
than successor?
I assume because it's easier for someone to refer to something that
was just written in the preceding line(s) than something that hasn't
been written yet. Of course, documentation
On Thu, Jun 21, 2007 at 09:21:13PM +0100, Smylers wrote:
: Damian Conway writes:
:
: > Here's the first draft (documented in Pod 6, of course ;-).
: >
: > =head3 Ambient aliases
: >
: > The C> formatting code specifies an B antecedent>.
:
: Please can you explain the reasoning for choosing ante
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
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
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
> heavil
Damian Conway writes:
> Here's the first draft (documented in Pod 6, of course ;-).
>
> =head3 Ambient aliases
>
> The C> formatting code specifies an B antecedent>.
Please can you explain the reasoning for choosing antecedent, rather
than successor?
I'm not disagreeing with your choice, merel
Smylers reported:
I was with you right up until the mention of C<=encoding>; what's that
got to do with anything?
C&P bug. Patched. Thanks!
Damian
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 I an instance of an
> L. Hence there is no paragraph
> or delimited fo
> 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
> 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 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
> > then publish your proposal for consideration here?
>
> Couldn't most of this be figured out by making Pod6 extensible (or
> whatever the right te
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 u
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. If we are to ever have consisten
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
the
* Damian Conway ([EMAIL PROTECTED]) [070621 01:45]:
> Mark Overmeer wrote:
> >This is exactly the form of documentation you do *not* want the
> >user to write, for various reasons:
> Well, I agree it is the form that "you" (singular, specific) do not want;
> but I'm not sure it's bad for "you" (p
Mark Overmeer wrote:
This is exactly the form of documentation you do *not* want the
user to write, for various reasons:
Well, I agree it is the form that "you" (singular, specific) do not want; but
I'm not sure it's bad for "you" (plural, generic) to write in all cases. ;-)
* The expli
* 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
Here's the first draft (documented in Pod 6, of course ;-).
Feedback and suggestions are most welcome.
(But please don't bother explaining to me this feature won't suffice
as the high-level automatic code-to-documentation mechanism that Markov
has been championing. I promise that I'm very well
30 matches
Mail list logo
