Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Sam Vilain
Damian Conway wrote: [No, I'm not back; I'm just passing by. But I feel that I need to comment on this whole issue] Thanks! This message has lots of useful information that I would have otherwise probably missed. It seems that the basic premise of the POD document object model gels well with t

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Damian Conway
Oh, and I forgot to mention: In the contents of any block, any line with '=' in column zero and a whitespace character in column 1, has those two characters removed when the contents are extracted. So you can write: =begin data POSSIBLE_POD_DIRECTIVES = = =doh -- Oh, dear! Oh frikking dear! = =r

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Damian Conway
[No, I'm not back; I'm just passing by. But I feel that I need to comment on this whole issue] Even before Brian announced Kwid, I was privately suggesting to Larry that Markdown (http://daringfireball.net/projects/markdown/) was an excellent evolution of mark-up notations and might be well sui

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread David Storrs
On Thu, Mar 17, 2005 at 05:04:53PM -0500, Aaron Sherman wrote: > On Thu, 2005-03-17 at 12:28, Brian Ingerson wrote: > > > The interesting thing to me is that all 3 syntaxes map over the same > > data model and thus are easily interchangable. > > It is, however, contrary to the spirit of POD for

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread gcomnz
On Thu, 17 Mar 2005 16:16:00 -0700, gcomnz <[EMAIL PROTECTED]> wrote: Brent 'Dax' Royal-Gordon <[EMAIL PROTECTED]> wrote: >By the way, I think I've seen a few people suggest some sort of >syntax-switching mechanism for "Pod6". The day people have to think >about what dialect of Pod they're usin

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Sam Vilain
Aaron Sherman wrote: Sam "mugwump" Vilain refers to each of these syntaxes as /Pod dialects/. He is working on more formally defining the common model or "AST" that these dialects map to. Why? Seriously, why on earth do you want to encourage the proliferation of variant markup languages?! There are

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Aaron Sherman
On Thu, 2005-03-17 at 17:07, Brent 'Dax' Royal-Gordon wrote: > Aaron Sherman <[EMAIL PROTECTED]> wrote: > > and the hacks in > > pod syntax (e.g. C<< < >>) to get around this are glaring anti- > > huffmanisms. > > Whatever bracketing character we decide to use, there will always be > occasions wh

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Brent 'Dax' Royal-Gordon
Aaron Sherman <[EMAIL PROTECTED]> wrote: > > Specifically, I like the use of angle brackets in Pod. Angle brackets > > are simple, distinctive shapes; they remain wide in variable-width > > This is aesthetic preference. I could cite the reasons that I have an > aesthetic preference for the other

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Aaron Sherman
On Thu, 2005-03-17 at 12:28, Brian Ingerson wrote: > The interesting thing to me is that all 3 syntaxes map over the same > data model and thus are easily interchangable. The other interesting > thing is that all three could be supported without affecting the Perl5 > or Perl6 syntax proper. If an

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Aaron Sherman
On Thu, 2005-03-17 at 16:39, Juerd wrote: > Aaron Sherman skribis 2005-03-17 16:30 (-0500): > > > See PodTables in the Pugs wiki. > > Or see the archive of this list, where we hammered it out previously. > > Since when is anything in Perl 6, except its name, set in stone? > > PodTables is a more

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Juerd
Aaron Sherman skribis 2005-03-17 16:30 (-0500): > > See PodTables in the Pugs wiki. > Or see the archive of this list, where we hammered it out previously. Since when is anything in Perl 6, except its name, set in stone? PodTables is a more detailed and more consistent approach to a suggestion I

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Aaron Sherman
On Thu, 2005-03-17 at 09:54, Juerd wrote: > > > Pod needs incremental improvements--tables > > Oops, forgot that one. I'll add it tonight, when I get home from work. > > See PodTables in the Pugs wiki. Or see the archive of this list, where we hammered it out previously. YMMV. I'll have the sec

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Brian Ingerson
On 17/03/05 00:49 -0500, Aaron Sherman wrote: > On Wed, 2005-03-16 at 13:42 -0800, Brian Ingerson wrote: > > Well, look over AJS Kwid, and see what you think. The bullet syntax you > give could work fine as a replacement for what I demonstrate, but I > think everything else is pretty much 1:1. Now

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Juerd
Aaron Sherman skribis 2005-03-17 8:30 (-0500): > This is aesthetic preference. I could cite the reasons that I have an > aesthetic preference for the other syntax, but the reality is that angle > brackets aren't angle brackets; they are less-than (E) and greater- > than signs (E). We ignore this f

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Aaron Sherman
On Wed, 2005-03-16 at 15:09 -0800, David Storrs wrote: > C[$x[0] > $y] # hmmm...parser ok with that? > C[$x[0] > $] # hmmm...error, but what was intended: $y] or $]]? In the former case, it's fine. See the grammar I sent last night. In the latter case, you would get balanced-[] matching, an

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Aaron Sherman
On Thu, 2005-03-17 at 02:17 -0800, Brent 'Dax' Royal-Gordon wrote: > David Storrs <[EMAIL PROTECTED]> wrote: > > Aside from links, that's pretty much the entire perlpodtut boiled down > > into 7 bullets; a little experimentation to get the hang of it and it > > all holds together nicely, easy to re

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-17 Thread Brent 'Dax' Royal-Gordon
David Storrs <[EMAIL PROTECTED]> wrote: > Aside from links, that's pretty much the entire perlpodtut boiled down > into 7 bullets; a little experimentation to get the hang of it and it > all holds together nicely, easy to remember. Yes, yes, yes. Pod is one of the things Perl 5 did almost exactly

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-17 Thread Mark Overmeer
> On Mon, 14 Mar 2005 20:54:20 -0500 > Stevan Little <[EMAIL PROTECTED]> wrote: > > My proposal is for an extensible version of POD. * John van Krieken ([EMAIL PROTECTED]) [050316 07:40]: > Did any of you look at the excelent work Mark Overmeer did on OOdoc? You're right. Actually, the most impor

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Aaron Sherman
On Wed, 2005-03-16 at 13:42 -0800, Brian Ingerson wrote: First off, thanks for your kind responses. I'm sure I just got confused by some web page I was looking at, and overwrote part of my stack that I'd just populated from the Kwid doc. And thanks also for pointing me to the Kwid docs where they

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread David Storrs
On Wed, Mar 16, 2005 at 01:30:04PM -0500, Aaron Sherman wrote: > On Wed, 2005-03-16 at 12:25, David Storrs wrote: > > > I quite like <> as the bracketing characters. They are > > visually distinctive, they connect well with their adjacent C/X/L/etc > > without visually merging into it (compare L

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Brian Ingerson
On 16/03/05 14:56 -0500, Aaron Sherman wrote: > On Wed, 2005-03-16 at 14:24, Brian Ingerson wrote: > > > vs Kwid: > > > > `$x > $y` is about as *easy* as it gets in [Perl] > > > > Did you really read `perlkwid.kwid`? > > Yes, and can you please stop asking that question? I read it seve

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Brian Ingerson
On 16/03/05 14:33 -0500, Aaron Sherman wrote: > On Wed, 2005-03-16 at 14:17, Brian Ingerson wrote: > > > Kwid does this by formally changing > > > >X<...> > > > > into > > > >{X...X} > > Ok, where is THAT proposal?! I'm reading the doc that's in > doc/perlkwid.kwid in the pugs source

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Aaron Sherman
On Wed, 2005-03-16 at 14:24, Brian Ingerson wrote: > vs Kwid: > > `$x > $y` is about as *easy* as it gets in [Perl] > > Did you really read `perlkwid.kwid`? Yes, and can you please stop asking that question? I read it several times, and you're starting to get just this side of insultin

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Aaron Sherman
On Wed, 2005-03-16 at 14:17, Brian Ingerson wrote: > Kwid does this by formally changing > >X<...> > > into > >{X...X} Ok, where is THAT proposal?! I'm reading the doc that's in doc/perlkwid.kwid in the pugs source tree. Hmmm... odd, I just did an update and it's GONE now... was I loo

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Brian Ingerson
On 16/03/05 13:30 -0500, Aaron Sherman wrote: > On Wed, 2005-03-16 at 12:25, David Storrs wrote: > > > I quite like <> as the bracketing characters. They are > > visually distinctive, they connect well with their adjacent C/X/L/etc > > without visually merging into it (compare L with L[foo]), and

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Brian Ingerson
On 16/03/05 12:00 -0500, Aaron Sherman wrote: > On Tue, 2005-03-15 at 13:48, Brian Ingerson wrote: > > Aaron, > > > > Upon reading this, it is unclear to me whether you have read about the > > Kwid format or you are simply guessing that Kwid is the same syntax > > used by Kwiki. > > I read the Kw

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Aaron Sherman
On Wed, 2005-03-16 at 12:25, David Storrs wrote: > I quite like <> as the bracketing characters. They are > visually distinctive, they connect well with their adjacent C/X/L/etc > without visually merging into it (compare L with L[foo]), and in > the circumstance that you want to bracket an unbal

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread David Storrs
On Wed, Mar 16, 2005 at 12:00:28PM -0500, Aaron Sherman wrote: > > The one obvious thing to POD users is the replacement of <> with [] or > {}. Why is this? Because < and > are used in un-balanced ways in a large > number of situations, so they should not be the primary bracketing > constructs.

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-16 Thread Aaron Sherman
On Tue, 2005-03-15 at 13:48, Brian Ingerson wrote: > Aaron, > > Upon reading this, it is unclear to me whether you have read about the > Kwid format or you are simply guessing that Kwid is the same syntax > used by Kwiki. I read the Kwid documentation from the Pugs distribution in depth.

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-16 Thread Adam Kennedy
For things like MMD --- I'd like to traverse the hypertext 'linkbacks' to any given method. Which method *exactly* will get called in the super class? A hypertext documentation system that introspects on classes could help here. Wouldn't it also be good to link back to the modules that use

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread John van Krieken
On Mon, 14 Mar 2005 20:54:20 -0500 Stevan Little <[EMAIL PROTECTED]> wrote: Did any of you look at the excelent work Mark Overmeer did on OOdoc? > Gang, > > My proposal is for an extensible version of POD. Basically what XML is > > to HTML/SGML, this will be for POD. This is a very very very ro

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-15 Thread Brian Ingerson
t-Description: Forwarded message - Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT) > From: Aaron Sherman <[EMAIL PROTECTED]> > Date: Tue, 15 Mar 2005 11:43:39 -0500 > To: Stevan Little <[EMAIL PROTECTED]> > Cc: perl6-compiler@perl.org > Subject: Re: [RFC] A more exten

Re: [Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-15 Thread Juerd
Aaron Sherman skribis 2005-03-15 11:46 (-0500): > = heading level 1 > == heading level 2 > =begin list I see this going wrong with =heading level 1 already. I like the numbers in =headN too, by the way, as it makes inconsistencies easier to spot. > And then replaced [...] and [=

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Nigel Hamilton
I agree. I think the biggest mistake Perl 6's documentation system could make is to make it Javadoc-style automatic. This is one of those weird, backwards, cultural decisions, where we actually want to make the programmer's life a little harder. When I (seldomly) progam in Java, I find it very ha

[Fwd: Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)]

2005-03-15 Thread Aaron Sherman
Wherein I propose (to the wrong list, sigh) a re-envisioning of Kwid in a more POD-like form. I did leave out some POD markup forms. Assume that, if I did not mention them, then I think they should keep the same prefix character (e.g. X<>) --- Begin Message --- On Tue, 2005-03-15 at 09:37, Stevan

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Aaron Sherman
On Tue, 2005-03-15 at 11:38, Stevan Little wrote: > On Mar 15, 2005, at 10:58 AM, Patrick R. Michaud wrote: > > Without commenting on the merits of any of the proposals, I'll > > note that discussions about changing POD are probably design-level > > discussions that belong on p6l instead of p6c (wh

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Aaron Sherman
On Tue, 2005-03-15 at 09:37, Stevan Little wrote: > On Mar 15, 2005, at 12:54 AM, Nigel Hamilton wrote: > > There is a need for a higher level 'structural' documentation that > > hypertext is well suited to cover - something that spans more than one > > module. This will be especially import

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Stevan Little
On Mar 15, 2005, at 10:58 AM, Patrick R. Michaud wrote: Without commenting on the merits of any of the proposals, I'll note that discussions about changing POD are probably design-level discussions that belong on p6l instead of p6c (which are implementation decisions). You are absolutely correct. I

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Patrick R. Michaud
Without commenting on the merits of any of the proposals, I'll note that discussions about changing POD are probably design-level discussions that belong on p6l instead of p6c (which are implementation decisions). I don't mind if it's discussed here, but p6c is really the forum for "how do we impl

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Nigel Hamilton
All that said I think a per-module perldoc documentation reader is still very important too ... maybe your design could allow for traversable HTML conversion in the future? Well my idea is to not dictate the eventual output. But to create a system which allows the most meta-data/contextual-info

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Luke Palmer
Stevan Little writes: > Introspection is nice, but I disagree that documentation should be that > transparent. One of the nice things I have found about perl and CPAN in > particular is that many people tend to document their modules very > well. Which not only includes information about method/

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-15 Thread Stevan Little
On Mar 15, 2005, at 12:54 AM, Nigel Hamilton wrote: Hi Steven, Hello Nigel, I think one of the great features of JavaDoc is the ability to generate hyperlinked documentation - so someone can walk the inheritance/interface hierarchy within their browser. It also provides consistency across all J

Re: [RFC] A more extensible/flexible POD (ROUGH-DRAFT)

2005-03-14 Thread Nigel Hamilton
Hi Steven, I think one of the great features of JavaDoc is the ability to generate hyperlinked documentation - so someone can walk the inheritance/interface hierarchy within their browser. It also provides consistency across all Java packages. For things like MMD --- I'd like to traverse the