State of Design Documents
Joshua Gatcomb
Designing a language isn't easy - I get that. Opening up the design
process to the entire community and filtering everyone's "good" ideas
certainly doesn't make this any easier. My concern is that these
difficulties are being aggravated because the design documents
(Synopses) are not kept up to bleeding edge date.
There are currently 12 Synopses available to implement code from but
there are still 19 more unpublished (I excluded formats in chapter 7
for obvious reasons). See "Perl6 Timeline By Apocalypse" for details:
http://perlmonks.org/index.pl?node_id=332117
I am sure that a great deal of that unpublished work has already been
decided and yet there is no end to revisiting old problems on this
list and musings of "didn't @larry say 'X' about that?".
I know that decisions are subject to change but having the current
state of decisions in a single location (Synopses) would be a great
benefit to all. I am a firm believer in not complaining unless you
have an idea about how to solve the problem, so here goes:
Put the design documents into public change control. Read access to
be granted globally with write access to be limited to @larry
initially. The community posts patches where the bulk of the work is
done and @larry makes any necessary modifications and commits. If
even that work load proves to be too much, perhaps common mortals get
granted commit access on a case-by-case basis.
Cheers,
Joshua Gatcomb
a.k.a. Gat
(240) 568-5675
Patrick R. Michaud
> I know that decisions are subject to change but having the current
> state of decisions in a single location (Synopses) would be a great
> benefit to all. I am a firm believer in not complaining unless you
> have an idea about how to solve the problem, so here goes:
>
> Put the design documents into public change control. Read access to
> be granted globally with write access to be limited to @larry
> initially. The community posts patches where the bulk of the work is
> done and @larry makes any necessary modifications and commits. If
> even that work load proves to be too much, perhaps common mortals get
> granted commit access on a case-by-case basis.
This already exists -- the design documents are all available from
http://svn.perl.org/perl6/doc/trunk . And I've already volunteered
to review/apply patches to the design documents or forward them to
the appropriate people for review -- there just haven't been a lot
of patches submitted. (p6l and/or p6c are probably appropriate forums
for this.)
Pm
Joshua Gatcomb
> This already exists -- the design documents are all available from
> http://svn.perl.org/perl6/doc/trunk . And I've already volunteered
> to review/apply patches to the design documents or forward them to
> the appropriate people for review -- there just haven't been a lot
> of patches submitted. (p6l and/or p6c are probably appropriate forums
> for this.)
Ok, admittedly I was playing a bit dumb. I knew about the repository
I just didn't think it was general knowledge. I was also unaware that
patches had been requested with a volunteer to act as the approving
authority.
Hmmm. Thanks. I guess I will have to go back over the questions I
have asked and see if any decisions were rendered not relfected in
docs and be a pioneer.
>
> Pm
>
Cheers,
Joshua Gatcomb
a.k.a. L~R
Joshua Gatcomb
> Hmmm. Thanks. I guess I will have to go back over the questions I
> have asked and see if any decisions were rendered not relfected in
> docs and be a pioneer.
Ok, are there any guidelines for what should and should not be put
forward as a patch. I can see 3 key areas of concern:
1. Framework for unwritten Synopses (so we know what goes where)
2. Heading placeholders for written Synopses with missing information
3. Decisions rendered by @larry (or should it only be $larry) on the
list that are not yet in the corresponding Synopsis
I have included a sample framework for chapter 17. Theoretically,
someone could then go search the archives for decision points in any
of those headings and fill in the blanks. Is this what you envisioned
or were you thinking only minor tweaks to existing documents?
Patrick R. Michaud
> Ok, are there any guidelines for what should and should not be put
> forward as a patch. I can see 3 key areas of concern:
>
> 1. Framework for unwritten Synopses (so we know what goes where)
> 2. Heading placeholders for written Synopses with missing information
> 3. Decisions rendered by @larry (or should it only be $larry) on the
> list that are not yet in the corresponding Synopsis
I think any of these are candidates for patches. Certainly it's easier
for others to respond to (and suggest further patches to) specific written
proposed documents than it is to try to find things in the mailing list
threads.
For anything that doesn't come from @Larry or $Larry, I think we can
perhaps provide a notation that the item is "draft" or "proposed" status
if there's any doubt about its ultimate acceptance in Perl 6. It's again
much easier to do a "grep draft" on the design document files to find
potentially unblessed items than it is to search through the p6l archives.
> I have included a sample framework for chapter 17. Theoretically,
> someone could then go search the archives for decision points in any
> of those headings and fill in the blanks. Is this what you envisioned
> or were you thinking only minor tweaks to existing documents?
I'm envisioning anything that helps advance the state of the documentation
and Perl 6 development. In that sense, I think that even templates and
placeholders can be helpful as long as they don't lead people down the
wrong path (or as long as they're fairly up front about "this might be
the wrong path").
Pm
Patrick R. Michaud
> On Fri, Jun 10, 2005 at 02:36:52PM -0400, Joshua Gatcomb wrote:
> > Ok, are there any guidelines for what should and should not be put
> > forward as a patch.
> For anything that doesn't come from @Larry or $Larry, I think we can
> perhaps provide a notation that the item is "draft" or "proposed" status
> if there's any doubt about its ultimate acceptance in Perl 6. It's again
> much easier to do a "grep draft" on the design document files to find
> potentially unblessed items than it is to search through the p6l archives.
FWIW, Larry also responded on perlmonks:
However, there are no general guidelines for how to document
the as-yet undesigned parts of the design. The best you can do
is to make a guess consistent with the current design and see if
anyone carps about it. A certain willingness to be sincerely
misguided goes with the territory. :-)
So, this sounds to me like framework patches could be useful and helpful.
It's also a useful reminder that none of use completely knows where the
Perl 6 design will end up, so guesses -- even incorrect ones -- are a
often a step forward.
Going a bit further than this... On #perl6 today we observed that
it might be helpful to know which parts of the documents others,
especially members of @Larry, already have designs upon (i.e., have
a strong desire or intention to write that section because of its
potential impacts to other parts of Perl 6 design). This would help
potential contributors to know which sections are already being
"thought about" by the design team, even if they're not being turned
into documents yet, and which sections might be open for contributions
from the community at large. Even a simple "section authorship claimed
by so-and-so" notation in placeholder documents would be helpful.
At any rate, I'll moderate patches to the design documents along these
lines, unless/until someone tells me not to do it. :-) And if any of
@Larry can let me know of any sections they feel strongly about, I'll
build and maintain notations to that effect in the documents.
Pm
Patrick R. Michaud
>
> > I have included a sample framework for chapter 17. Theoretically,
> > someone could then go search the archives for decision points in any
> > of those headings and fill in the blanks.
Since it might not have been clear from my earlier post -- I've
now committed the S17 framework draft into the repository. Thanks.
Pm
Joshua Gatcomb
> Since it might not have been clear from my earlier post -- I've
> now committed the S17 framework draft into the repository. Thanks.
I am now questioning using "Perl6 Timeline By Apocolypse" as reference
material. I am rather interested in seeing the specs for pack/unpack
so I went about finding where it should go:
There are 2 RFCs listed for A09 for pack/unpack
142 Enhanced Pack/Unpack
247 pack/unpack C-like enhancements
There is an RFC for A13 regarding distinguishing packed data
258 Distinguish packed data from printable strings
The rest of the RFCs for pack/unpack fall into A29
246 pack/unpack uncontrovercial enhancements
248 enhanced groups in pack/unpack
249 Use pack/unpack for marshalling
250 hooks in pack/unpack
Now S09 and S13 have already been written but do not include the
details regarding pack/unpack.
The patch to S29 is obvious - just add a heading for pack/unpack and
hope someone fills in the blanks.
The patch for S13 is more difficult since I don't believe it warrants
a full heading. Probably just needs a guess as to how to expose the
flag to return a bool value i.e. $string.packed, comment about the
'packed' warnings/strictures pragma, and stick it the "right" place.
The patch to S09 has me stumped.
Is there any other reference material I can use to put together solid
frameworks that are closely representative to what @larry might
produce?
> Pm
Larry Wall
: On 6/13/05, Patrick R. Michaud <pmic...@pobox.com> wrote:
:
: > Since it might not have been clear from my earlier post -- I've
: > now committed the S17 framework draft into the repository. Thanks.
:
: I am now questioning using "Perl6 Timeline By Apocolypse" as reference
: material.
Heh, that classification was a fast guess about RFCs made more than
4 years ago. I'm amazed it's stood up as well as it has, even where
it hasn't.
: I am rather interested in seeing the specs for pack/unpack
: so I went about finding where it should go:
:
: There are 2 RFCs listed for A09 for pack/unpack
: 142 Enhanced Pack/Unpack
: 247 pack/unpack C-like enhancements
:
: There is an RFC for A13 regarding distinguishing packed data
: 258 Distinguish packed data from printable strings
:
: The rest of the RFCs for pack/unpack fall into A29
: 246 pack/unpack uncontrovercial enhancements
: 248 enhanced groups in pack/unpack
: 249 Use pack/unpack for marshalling
: 250 hooks in pack/unpack
I think at this point we should assume that any RFCs that haven't
been officially blessed should be considered officially suspect,
and prior art (Perl 5) should generally take precedence unless we
decide otherwise. If something seems too good to leave out, we can
talk about it here.
That being said, it's pretty clear that there are some things that
are suboptimal about Perl 5's pack/unpack.
: Now S09 and S13 have already been written but do not include the
: details regarding pack/unpack.
:
: The patch to S29 is obvious - just add a heading for pack/unpack and
: hope someone fills in the blanks.
:
: The patch for S13 is more difficult since I don't believe it warrants
: a full heading. Probably just needs a guess as to how to expose the
: flag to return a bool value i.e. $string.packed, comment about the
: 'packed' warnings/strictures pragma, and stick it the "right" place.
:
: The patch to S09 has me stumped.
:
: Is there any other reference material I can use to put together solid
: frameworks that are closely representative to what @larry might
: produce?
Not really, except insofar as we've talked about compact classes of
native types working like C structs. There are lots of nitty things
we can fix with pack/unpack, but the basic underlying problem is
that pack/unpack are defined operationally rather than declaratively.
As a kind of funny bytecode for serializing operations, it's rather
powerful, but you'll notice that C gets by without such operationally
defined structs.
So I think that what we're going to end up with is a pack/unpack engine
not so different from what we have, but it will very rarely be used
directly. Rather, any compact class can automatically serialize/deserialize
automatically, but can also be asked for its pack pattern for explicit
control of pack/unpack when you want that.
At the same time, I think the pack/unpack bytecode is not necessarily
the final compiled form, since many of them could be "jitted" to PASM
code that doesn't need to be interpreted by a pack/unpack engine,
but handled directly by the VM, and maybe even jitted down to real
machine code. That implies that either we modify the pack/unpack
interface to allow explicitly produced compiled objects via MMD:
@foo = unpack(packcomp("H*"), $string)
or we rely on caching of the compiled pack program with the supplied string.
@foo = unpack($pk, $string); # recompiled only if $pk changes
Arguably the latter is more user friendly, and doesn't commit to
the compiled form if it turns out to actually be more efficient to
interpret the pack bytecode directly. And we already presumably do
that sort of caching for strings interpreted as rules.
Larry
Joshua Gatcomb
> Heh, that classification was a fast guess about RFCs made more than
> 4 years ago. I'm amazed it's stood up as well as it has, even where
> it hasn't.
I agree, and lacking anything I could find more recent, initially
thought it was the right way to go.
> I think at this point we should assume that any RFCs that haven't
> been officially blessed should be considered officially suspect,
> and prior art (Perl 5) should generally take precedence unless we
> decide otherwise. If something seems too good to leave out, we can
> talk about it here.
There is another question at the Monastery entitled "What's in Perl
6?" asking specifically which RFCs have been accepted, rejected, and
of course the ones somewhere in the middle.
about http://perlmonks.org/index.pl?node_id=96184
The written Apocolypses answered that question for the applicable RFCs
but there are two problems. The first is that we are now primarily
focusing on Synopses. The second is that it is hard to frame synopses
without the knowledge of which RFCs are in what state.
>
> That being said, it's pretty clear that there are some things that
> are suboptimal about Perl 5's pack/unpack.
My primary focus here is on the design documents. I believe that it
will be easier to focus on what is left my having a means to measure.
Using the analogy of a house, once the frame is up it is easy to walk
in and see that the master bedroom is finished while the kitchen
hasn't been started. I believe it will be easier to point people to
reference material then it is to rehash questions repeatedly on the
list. I believe it will be easier for someone to modify documentation
if an organized framework tells them where it needs to go.
I freely admit I may be living in the clouds and my well intentioned
idea is good in theory but hard to do in reality.
If you, or anyone else, can see a clear way to move forward for those
outside of the cabal to help - we would certainly appreciate it.
> Not really, except insofar as we've talked about compact classes of
> native types working like C structs. There are lots of nitty things
> we can fix with pack/unpack, but the basic underlying problem is
> that pack/unpack are defined operationally rather than declaratively.
Sorry, perhaps I should have been more clear. This was a general
question with regards to the design documents and not specifically
with pack/unpack. So is there anything those of us not in @larry can
do to help out with the design documents and specifically where can we
go to get reference material?
> Larry
>
As a side note, the only thing I would like to see in pack/unpack is a
way to make the following task easier:
You have to read records in the following way:
2 bytes = what type of record you have
3 bytes = how long the record value is
? bytes = value of record which is determined by previous read
In p5, you need to keep track of your offset and skip that number of
bytes each time. It would be nice if p6 could somehow make that
easier. Again, my focus is on the design docs and not on pack/unpack.
I just used it as a discussion point since it is what I was working
on at the time.
Joshua Gatcomb
a.k.a. L~R
Christian Renz
>native types working like C structs. There are lots of nitty things
>we can fix with pack/unpack, but the basic underlying problem is
>that pack/unpack are defined operationally rather than declaratively.
I think it's worth taking a look at Marcus Holland-Moritz'
powerful Convert::Binary::C ( http://search.cpan.org/dist/Convert-Binary-C/ ).
It already offers a way to declaratively convert to/from binary
data, which could serve as inspiration for a similar Perl6 interface.
Greetings,
Christian Renz
--
cr...@web42.com - http://www.web42.com/crenz/ - http://www.web42.com/
"If God were a Kantian, who would not have us till we came to Him from
the purest and best motives, who could be saved?"
-- C.S. Lewis, The Problem of Pain