Re: State of PDD 0

[Ask Bjoern Hansen]

On Tue, 20 Feb 2001, Ask Bjoern Hansen wrote:

> I have created perl6-announce-pdd. Mail [EMAIL PROTECTED]
> for clues.

by the way, Adam Turoff was kind and volunteered to take the PDD
archive pumpkin like he was handling the bazillion RFC's.

[EMAIL PROTECTED] will thus go to him now. Be sure to buy him an
extra beer or three at TPC[1].


 - ask

[1] or just go and pick it up at the bar for him if they are free. :)

-- 
ask bjoern hansen - 

Re: ANNOUNCE: smokers@perl.org Discussion of perl's daily buildandsmoke test

[Richard Foley]

Johan Vromans wrote:
> 
> As an active non-smoker, 
Me too - an _EX_ which is perhaps worse :-)

> I'd appreciate a different name.
How about:

[EMAIL PROTECTED]# 

[EMAIL PROTECTED]   # bleeding edge?

[EMAIL PROTECTED]   # not very exciting...

[EMAIL PROTECTED] # hmmm?

???

Ciao
-- 
Richard Foley
Ciao: shorter than Aufwiedersehen

Re: ANNOUNCE: smokers@perl.org Discussion of perl's daily buildandsmoke test

[Richard Foley]

Johan Vromans wrote:
> 
> As an active non-smoker, 
Me too - an _EX_ which is perhaps worse :-)

> I'd appreciate a different name.
How about:

[EMAIL PROTECTED]

[EMAIL PROTECTED]

[EMAIL PROTECTED]

(daily|weekly|...)build(er)*[EMAIL PROTECTED]  # <- ?

It's in the subject line.

???

Ciao
-- 
Richard Foley
Ciao: shorter than Aufwiedersehen

Re: RFC archive?

[Ask Bjoern Hansen]

On Tue, 20 Feb 2001, Matthew Cline wrote:

> What's the URL for the RFC archive?

always try google first.

  http://www.google.com/search?q=perl6+rfc+index

 would have let you straight to http://dev.perl.org/rfc/


 - ask

-- 
ask bjoern hansen - 

Re: C Garbage collector

[Ask Bjoern Hansen]

On Wed, 21 Feb 2001, Alan Burlison wrote:

> Alan Burlison wrote:
> 
> > I've attached the HTML
> 
> Well it was there when I sent it... does this list strip attachments or
> something?

yes, it does. It is usually just misconfigured mailers or spam.

-- 
ask bjoern hansen - 

RE: C Garbage collector

[NeonEdge]

I agree with Damien that the Sun description sounds less portable, which we all
know in the Perl world is crucial (>80 ports)(although Sun mentions 16-bit
DOS/Win). Any GC implementation needs to try to 'not break' the existing stuff.
Other questions are somewhat dependent upon what language is used to implement
(both GC descriptions are C or C++ dependent which is ok by me, but I'm a
masochist). I've been off the list since RFCs closed, so does anyone know if
there's been any further thoughts on the implementation language?
Grant M.

require < 6.x

[NeonEdge]

This is probably way too late, but does this make any sense: could p6 allow
(for the first few versions anyway) a "require <6;" directive?
   My thought was that during the install process, the admin would be prompted
as to whether or not they wished to retain 'full' backward compatibility, and
if so the build would simply rename the old Perl to perl5.6.0. Then, when p6
encountered the 'require <6;' directive, it would simply shell to the old Perl.
This could allow two things:
1.> give the implementers more time to develop and debug the conversion
scripts.
2.> allow p6 to implement more robust changes to the language.
Or maybe the other way around: If 'full' was selected during the build,
then p6 would only be run if 'require 6.x.x;' were encountered.
Just a thought (maybe a bad one),
Grant M.

Re: State of PDD 0

[Bryan C . Warnock]

On Tuesday 20 February 2001 21:45, Adam Turoff wrote:
> PDDs, like the RFCs that preceded them, will need to serve multiple
> purposes.  One of them will be to catalog (and *name*) ideas that
> keep coming up, including the bad ideas (like the |||= operator)
> that we're tired of discussing.  I don't think anyone expects each
> of N PDDs to get us 1/Nth closer to Perl6.

Except it may be possible to keep the RFC structure for the "we're NOT" 
historical section.  I would much rather have a clean section on "This Is 
Perl" than to wade through N + X documents just to glean the N clues that 
I'm after.

> 
> Some PDDs, especially Informational and possibly Experimental,
> might need to precede knowledgeable discussion.  If so, then
> Standards-track need to have the requirement that they summarize
> some amount of discussion on the list(s), and that requirement is
> enforcable (i.e., no PDDs out of left field).  

Well, we could move to a sponsorship-type model.  Since you need a WG Chair 
to move it past proposal stage, simply make that a requirement for that 
stage too.   In order to submit a Standards-track Proposal, you need a WG 
Chair, etc, to sponsor it.

That would also allow several people to put together differing proposals 
for the times that we don't have prior discussion.  Dan, for instance, 
could call for proposals for locality handling, and several folks could 
write their own comprehensive (ie, no hand-waving "and {poof} magic 
happens") PDD of how to implement it.  Only one need be accepted, the 
others can be archived with all the other Proposals for historical purposes 
- that was the whole point in not numbering Proposals in the first place.
But that seems to be merging again with the RFC process - so maybe not.

Of course, if we put too much structure in place, no one will use it, and 
we'll either see more non-experimental Experimental PDDs, or no PDDs at all.

> 
> That's a good idea, but I'm not entirely convinced that it's the
> only one, the fairest one or the most practical one.

I'm all ears.  Er... eyes.

-- 
Bryan C. Warnock
[EMAIL PROTECTED]

Re: ANNOUNCE: smokers@perl.org Discussion of perl's daily build andsmoke test

[Stephen P. Potter]

Lightning flashed, thunder crashed and Richard Foley <[EMAIL PROTECTED]> 
whispered:
|   [EMAIL PROTECTED]# 
| 
|   [EMAIL PROTECTED]   # bleeding edge?
| 
|   [EMAIL PROTECTED]   # not very exciting...
| 
|   [EMAIL PROTECTED] # hmmm?

People, please trim your CCs.  This does not need to be broadcast all over
the place.  It especially shouldn't be CCed to -announce.

-spp

lazy || and vtables

[David Mitchell]

Following up from a thread a couple of weeks ago,

Dan wrote:
> > Dave wrote:
> >Hmmm, I can't quite how that trick works. How whould the following get
> >evaluated:
> >
> >$opened || open(F, ...)
>
> The second PMC would point to a lazy list, so it wouldn't be evaluated 
> unless its value gets fetched.

Do you have any more details how this 'lazy list' would work?
The only way I can think is to have an 'execution' vtable type,
which initially holds a pointer to a CV or an area of bytecode or somat,
but when asked for it's value, executes itself and morphs into the result
of the expression.

Re: require < 6.x

[Simon Cozens]

On Wed, Feb 21, 2001 at 02:05:19PM -0500, Stephen P. Potter wrote:
> Lightning flashed, thunder crashed and "NeonEdge" <[EMAIL PROTECTED]> whisper
> ed:
> | This is probably way too late, but does this make any sense: could p6 allow
> | (for the first few versions anyway) a "require <6;" directive?
> 
> Do you understand how the current "require #;" works?  It already pretty
> much does what you want.  If you try to do something like
> 
>  perl5.6.0 -e 'require 6;'

I think what he wants is a corresponding "no 6". :)

-- 
In related wibbling, I can see an opening for the four lusers of the
Apocalypse... "I didn't change anything", "My e-mail doesn't work",
"I can't print" and "Is the network broken?".
- Paul Mc Auley

Re: Things have paused... really?

[schwern]

On Tue, Feb 20, 2001 at 12:10:53PM -0600, Garrett Goebel wrote:
> This is perhaps the 3rd recent "waiting for Larry" comment posted in the
> last week. I don't mind waiting... good things take time.

We'll hang ourselves tommorrow... unless Larry comes.  And if he
comes, we'll be saved.


-- 
Michael G Schwern   <[EMAIL PROTECTED]>   http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]>   Kwalitee Is Job One

Re: State of PDD 0

[David Mitchell]

"Bryan C. Warnock" <[EMAIL PROTECTED]> wrote:
> Well, there's also Meta stuff for discussion that we should probably 
> document as well.  As much as I disliked RFC, I also disliked PDD, as it 
> 'sounds' internal.  But do we create a new category for every new area we 
> attempt to document, or do we change the name to reflect something more 
> generic?  (The PDD has a Class field to distinguish between internals, 
> meta, and language already.)
> 
> If we go with mulitple documents, is the numbering scheme concurrent?

Sounds good to me.

Also, if we go down the 'have a competition to see who can write the best
PDD on subject X' path, can we replace the 'TBD' in unnumbered PDDs
with a short string chosen by the author? This allows us to (hopefully)
unqiuely refer to a document during disussions, but when a final winner
is chosen and given a number, the offical library can still pretend the
losers never existed, unless people look in the 'losers' section.
EG
PDD-dapm-GC

rather than

PDD-TDB

for my attempt at garbage collection or whatever.

[lenzo@cs.cmu.edu: Re: Unicode Consortium Membership]

[Simon Cozens]

Just a note, for anyone who's interested, that I'm thinking about getting Perl
membership in the Unicode Consortium. I'd ideally like to be able to get us
full voting rights, but that is prohibitively expensive.

Simon

- Forwarded message from "Kevin A. Lenzo" <[EMAIL PROTECTED]> -

From: "Kevin A. Lenzo" <[EMAIL PROTECTED]>
Subject: Re: Unicode Consortium Membership
To: Simon Cozens <[EMAIL PROTECTED]>
Cc: [EMAIL PROTECTED], [EMAIL PROTECTED]
X-Spam-Warning: ip250.pittsburgh11.pa.pub-ip.psi.net is in the DUL

I'm certainly interested in pursuing this.  We should certainly talk 
about it, and I do think you are correct.  Furthermore, donations to
fund this are a Great Thing, and make it more possible.

Kevin


On Tue, Feb 20, 2001 at 03:40:47PM +, Simon Cozens wrote:
> (Sorry, I don't know the best address to contact YAS decision-making-people on
> at the moment.)
> 
> It seems to me that Perl - especially with the advent of Perl 6 - would
> greatly benefit from representation on the Unicode Consortium. The Unicode
> Standard already contains disclaimers along the lines of 'but Perl does it
> differently...' We should be working with these guys, not against them.
> 
> Associate non-profit membership would get three people membership of the
> Unicode Consortium, including rights to access members-only data and mailing
> lists, a listing on the UC's home page and a link to our home page,
> (non-voting) rights to participate at Unicode Technical Committee meetings,
> and would cost $1200 per annum.
> 
> My consultancy, NetThink, would be interested in donating some or all of that
> money to YAS if YAS would then go on to apply for membership on Perl's behalf.
> 
> Thoughts?
> 
> Simon
> 
> -- 
> "He was a modest, good-humored boy.  It was Oxford that made him insufferable."

-- 

- End forwarded message -
-- 
Hi, this is Ken. What's the root password?

Re: End-of-scope actions: Toward a hybrid approach.

[schwern]

On Tue, Feb 20, 2001 at 02:19:18PM +, Simon Cozens wrote:
> Sort of. What I really wanted to do was to be able to say
> 
> sub foo { ... }
> builtinify(foo);
> 
> package bar;
> foo(); # Refers to main::foo
> package baz;
> foo(); # Refers to main::foo
> 
> (this is so that the forthcoming Safety::First module can produce exported
> functions available throughout the program)

Look at Dunce::Files.  I suspect we have similar spirits here, but I
never was able to solve the above problem.  Fortunately, I think I can
simply drop Sub::Versive into Dunce::Files in place of
Function::Override and have it be truly global.

I was about to say "What are the odds that someone will use
UNIVERSAL::AUTOLOAD?!" before realizing I use it in about three
modules. :(

Let me know what Safety::First does (is going to do)


> > Want to merge implementations?
> 
> I'm open to offers. Take a look at S::V and tell me what you think.

I was wondering how you were planning on doing this without a core
hack... and it looks like you're doing a core hack. :(

So, could you explain the CvGV magic there?  In POD form?  Preferably
in ext/Devel/Peek/Peek.pm?  (subtle hint, there's no docs)

The two things which worry me in this implementation is its reliance
on an autoloader (always icky) and the 5.6.1 requirement.  Is there
any way we can cut that down?

-- 
Michael G Schwern   <[EMAIL PROTECTED]>   http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]>   Kwalitee Is Job One

Re: Warnings, strict, and CPAN (Re: Closures and default lexical-scopefor subs)

[Sam Tregar]

On Wed, 21 Feb 2001, Bart Lateur wrote:

> Actually, it's pretty common. Only, most languages are not as forgiving
> as perl, and what is merely a warning in Perl, is a fatal error in those
> languages. Trying to read the value of an uninitialized variable, for
> example, that's commonly a fatal error. Failing to chdir, is another
> example.

Examples?  I know you're not talking about C or C++.  I'm pretty sure
you're not talking about Java - exception-handling renders the term "fatal
error" almost meaningless.

-sam

RE: require < 6.x

[NeonEdge]

On Wed, Feb 21, 2001 at 02:05:19PM -0500, Stephen P. Potter wrote:
> If they're going to have to go in and add a "require <6" already, its easier
> to just modify the #! line (and less coding for us).

Duh, <> the #! line. I'm awake now, though. ;)
Grant M.
I've gotta stop getting up before noon.

Re: require < 6.x

[Stephen P. Potter]

Lightning flashed, thunder crashed and "NeonEdge" <[EMAIL PROTECTED]> whisper
ed:
| This is probably way too late, but does this make any sense: could p6 allow
| (for the first few versions anyway) a "require <6;" directive?

Do you understand how the current "require #;" works?  It already pretty
much does what you want.  If you try to do something like

 perl5.6.0 -e 'require 6;'

you get the following error already:

Perl v6.0.0 required--this is only v5.6.0, stopped

I would expect when people install 6, they will keep their 5.6.x (or 5.8.x
or whatever) versions around.  They can then just modify their scripts to
call perl5.x.y instead of perl if they want to ensure they run under 5.  If
they're going to have to go in and add a "require <6" already, its easier
to just modify the #! line (and less coding for us).

Then, the scripts they do want run under 6, they can put "require 6;" in
and get the above error.

You might be able to convince people that perl6 should bomb (or
automagically run the p52p6 script) if it encountered a "require 5;".

-spp

Re: State of PDD 0

[Adam Turoff]

On Wed, Feb 21, 2001 at 07:44:51PM +, David Mitchell wrote:
> 
> Also, if we go down the 'have a competition to see who can write the best
> PDD on subject X' path, can we replace the 'TBD' in unnumbered PDDs
> with a short string chosen by the author? This allows us to (hopefully)
> unqiuely refer to a document during disussions, but when a final winner
> is chosen and given a number, the offical library can still pretend the
> losers never existed, unless people look in the 'losers' section.
> EG
>   PDD-dapm-GC
>   
> rather than
> 
>   PDD-TDB
> 
> for my attempt at garbage collection or whatever.

There are advantages with using simple enumeration for RFCs/PDDs.  (I'll
beat that dead horse only upon request.)

The disadvantage of switching to a more descriptive naming scheme
is that any identification attached to a PDD upon receipt must be
final; a PDD cannot be renumbered/renamed once it has been accepted
into the archives.  To do so would make it more difficult to search
the archives for discussion about an idea -- searching on PDD-std-vtbl
won't find the threads that lead to that standard, when it was
called PDD-sugalski-vtbl.

Perhaps a more descriptive prefix/suffix notation on PDDs would
improve upon the anonymous nature of RFCs/PDDs, so long as a core
name is assigned to a document never changes.

Z.

Re: require < 6.x

[Brent Dax]

NeonEdge wrote on 2/21/01 4.07:
...
>sense: could p6 allow (for the
>first few versions anyway) a
>"require <6;" directive?  My
...

This sounds to me like a good idea, especially if we implement some of the
other radical changes, such as implicit 'use strict' or major changes to
builtins.  Personally I'd have it be 'use perl5' (it's the difference
between making a new pragma and defining a third meaning for require [or
redefining its current meaning]) but that's a minor detail.  Unfortunately,
it may be too late.  Oh well...

--Brent Dax
Excuse typos, it's hahd to write on a Palm...

Re: Warnings, strict, and CPAN (Re: Closures and default lexical-scope for subs)

[Peter Scott]

Are we still having this discussion? :-)

At 07:23 PM 2/21/01 -0500, [EMAIL PROTECTED] wrote:
>Its true alot languages would consider many of Perl's warnings to be
>errors, that's not really analgous to what we're talking about here.
>
>Run-time errors aren't quite in the same spirit as run-time warnings.
>A run-time error is something the language defines as being explicitly
>bad or a mistake (even if it can be caught as an exception).  Run-time
>warnings are just the language saying, "excuse me, there might be a
>problem here".  An error is, "NO, YOU'RE WRONG!!"
>
>Errors and exceptions must be dealt with, else your program won't run.
>Warnings... they can be ignored.

I do not think there is hard dividing line between warnings and 
errors.  "Unable to establish network connection - saving file to local 
disk" means the program is still running afterwards.  The more 
fault-tolerant your program is, the more your errors look like 
warnings.  Is that message an error or a warning?

>   Warnings are often stylistic in
>nature, errors are not.  An error is often a very concrete indication
>that something is wrong, a warning is not (if it was, it should be
>promoted to an error).
>
>With that in mind, do we have any analogies?
>
>I can think of some GUI analogies.  Macster (the Macintosh Napster
>client)* requires that you confirm every download you cancel.
>Windows, by default, requires that you confirm everything you drop
>into the trash (or whatever they call it this week).  Most software
>installers require that you click [Accept] after reading the
>agreement.  Some even require that you scroll down to the bottom
>before letting you accept.
>
>The result?  People either shut them off or mindlessly click [Ok].
>Nobody** sits there and things "gee, do I really want to throw this
>out?"  Nobody reads software licenses.

Or government warnings on cigarettes.

>Its not that there's anything wrong with these ideas, but its the
>continual bombardment which dulls the senses against them.  If the
>user has internalized the need for them (say, they once deleted a file
>which cost them their job) then it might be helpful.
>
>Similarly, a wet-behind-the-ears programmer will not give Perl's
>warnings much credence if their program runs fine despite of them.
>They will be ignored until such time as they internallized, through
>error or teaching.

I suppose I'm in an exceptional class then, 'cos whatever language I'm 
using, any warning at any time causes me to stop what I'm doing, and fix 
the cause.  Even if that means selectively ignoring the warning through a 
pragma.  I've been doing this since I used Saber C (actually before that, 
too): fix the cause, or put an ignore directive in.  Never mind how picky 
it seems.

I am somewhat frightened by the prospect of anyone programming with a 
mindset that warnings are okay, and even more by the philosophy that we 
should cater more to them than more careful people.

What if the warnings were:

1/100 chance of destroying your files at this point... you win!
1/100 chance of producing incorrect output at this point... you win!
1/100 chance of losing user data at this point... you win!
...

What if the warnings boiled down to that anyway?
--
Peter Scott
Pacific Systems Design Technologies

Re: Warnings, strict, and CPAN (Re: Closures and default lexical-scope for subs)

[schwern]

Its true alot languages would consider many of Perl's warnings to be
errors, that's not really analgous to what we're talking about here.

Run-time errors aren't quite in the same spirit as run-time warnings.
A run-time error is something the language defines as being explicitly
bad or a mistake (even if it can be caught as an exception).  Run-time
warnings are just the language saying, "excuse me, there might be a
problem here".  An error is, "NO, YOU'RE WRONG!!"

Errors and exceptions must be dealt with, else your program won't run.
Warnings... they can be ignored.  Warnings are often stylistic in
nature, errors are not.  An error is often a very concrete indication
that something is wrong, a warning is not (if it was, it should be
promoted to an error).

With that in mind, do we have any analogies?

I can think of some GUI analogies.  Macster (the Macintosh Napster
client)* requires that you confirm every download you cancel.
Windows, by default, requires that you confirm everything you drop
into the trash (or whatever they call it this week).  Most software
installers require that you click [Accept] after reading the
agreement.  Some even require that you scroll down to the bottom
before letting you accept.

The result?  People either shut them off or mindlessly click [Ok].
Nobody** sits there and things "gee, do I really want to throw this
out?"  Nobody reads software licenses.  

Its not that there's anything wrong with these ideas, but its the
continual bombardment which dulls the senses against them.  If the
user has internalized the need for them (say, they once deleted a file
which cost them their job) then it might be helpful.

Similarly, a wet-behind-the-ears programmer will not give Perl's
warnings much credence if their program runs fine despite of them.
They will be ignored until such time as they internallized, through
error or teaching.


* I expect the Feds to be knocking down my door any minute now.
** s/Nobody/Just about no one/ for the picky.

-- 
Michael G Schwern   <[EMAIL PROTECTED]>   http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]>   Kwalitee Is Job One

newPMC() (was: Re: PDD 2, vtables)

[David Mitchell]

Dan Sugalski wrote:
> Grab one via a utility function. getPMC() or something of the sort.
>
> newPMC() ? ;-)

I think we shouldn't rule out the possibility of having multiple
newPMC() style functions for grabbing PMCs used for different activities
(eg lexicals vs tmps vs guaranteed-to-have-refcount<=1 vs whatever),
which may all have different allocation/GC schemes.
Heck, we might even consider having newPMC(N) returning a pointer to
a contiguous chuck of N PMCs; this might then allow us to have good locality
of reference for all the stuff in a scratchpad, for example.

I dont think we can have a sensible discussion of this until the GC PDD
is been released, but I thought I'd flag up the idea anyway.

Re: ANNOUNCE: smokers@perl.org.... Actaually have a good name sugest

[David Grove]

"John van V" <[EMAIL PROTECTED]> wrote:

 >
 > I actually have a good name...
 >
 > shakedown (as in cruise, matches CPANTS)

I thought cruise got famous because you couldn't CPANTS.

 > Personally I would want to pull away from reliance on any corporation
(ask
 > Dave Grove why)

Please don't.

I'm just waiting to see whether the Perl 6 specs finally get announced at
TPC 2001.

 > Keep in mind, we're still fighting the Randal Schwartz

Why? I know he did a 180 on me that blew my mind but I'm not aware of any
other problems. What don't I know?

(other than that, I'm not sure what you said... was that ancient
southwestern zulu?)

p

Re: Warnings, strict, and CPAN (Re: Closures and default lexical-scope for subs)

[Bart Lateur]

On Wed, 21 Feb 2001 16:01:39 -0500, [EMAIL PROTECTED] wrote:

>Has anyone actually used a language which has run-time warnings on by
>default?  Or even know of one?

Actually, it's pretty common. Only, most languages are not as forgiving
as perl, and what is merely a warning in Perl, is a fatal error in those
languages. Trying to read the value of an uninitialized variable, for
example, that's commonly a fatal error. Failing to chdir, is another
example.

So even with warnings on by default, Perl is still pretty mild.

-- 
Bart.

Re: Warnings, strict, and CPAN (Re: Closures and default lexical-scope for subs)

[schwern]

Has anyone actually used a language which has run-time warnings on by
default?  Or even know of one?

-- 
Michael G Schwern   <[EMAIL PROTECTED]>   http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]>   Kwalitee Is Job One

Re: Warnings, strict, and CPAN (Re: Closures and default lexical-scope for subs)

[schwern]

On Wed, Feb 21, 2001 at 05:32:50PM -0500, Sam Tregar wrote:
> Examples?  I know you're not talking about C or C++.  I'm pretty sure
> you're not talking about Java - exception-handling renders the term "fatal
> error" almost meaningless.

Well, an unhandled exception in Java is death for the program.

-- 
Michael G Schwern   <[EMAIL PROTECTED]>   http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]>   Kwalitee Is Job One

Re: PDD for code comments ????

[David Mitchell]

Based on the silence == assent prinicple, I think we have agreed:

1. we need "a relatively strict and standard way" to document code.
2. This is the time and place to discuss it.
3. The result of the discusssion should be a PDD.
4. Most commentary should appear within the src file itself, or it's useless.
5. Broad agreement with my proposal for mandatory per file, per section,
and per func/struct comments.
5a. Most of the structured comments should be extractable, even if we
don't immediately make use of them. Obviously stuff that would be meaningless
on its own shouldn't be extracted.

Since this as all agreed, we can now move onto 6:

> 6. Can we leave the details of pod/apidoc/rfc281 until 1..5 have been
> agreed?

ie we thrash this bit out, then I'll write it up as an improved version
of the PDD I scribbled earlier and submit it (now that I know how to
submit PDDs :-)

So here goes

I want to combine:

* "we need comments in the code" - me and a cast of thousands
* "we need a commentary file per src file" RFC281 and Simon Cozens
* "we need PDDs" - Dan and everyone

into a 3-layer hierarchy.

Take something like the IO system. At the top level, we have a PDD on
IO saying [this example is totally fictional]:

"we considered async, event, blah, etc but decided on async for the
following reasons: blah blah.
IO is be implemented by having a system-independent layer with
the following API, and"

ie a high-level document covering a whole subsystem.

When people code up the IO subsystem, they will end up with a collection
of src files, each implementing various aspects of it. Each (or most) src
file has an associated (but separate) file providing an overall commentary
for the code that is in the file. This describes low-level design decisons
and histories for the things implemented in that file. Eg it might say:

"We maintain a cache of IO handles, as it was found that this speeded
up blah blah."

Finally, there would be the individual comments within the source file.
Here, a section comment would be more specific to the here-and now coding,
eg

"This section implements the IO handle cache. It is maintained as a
doubley-linked list with IO_handle_root pointing to the head.
pop_io_handle() grabs the most recent handle by simply yanking it from
the head of the list, while push_io_handle() returns it to the head
unless..."

and the per-function comment for pop_io_handle() would say

/* grab most recently used handle from the handle cache */



I would expect that the sort of level of information provided by something
like perlguts.pod would naturally find its way spread between a PDD and
commentary file, while the comments in the src file itself are at a
lower level.

---|---

So, we need to decide whether we want a 3-level hierarchy like that
suggested, and once agreed, the stucture and/or tagging of the
commentary file and src comments.