[CVS ci] removed (was: removiing classes/intqueue.pmc)
Leopold Toetsch wrote: If no one hollers, I'll remove the IntQueue class. - only used in some tests AFAIK - functionality may be written in terms of intlist push/pop - has a weird syntax for queue/dequeue - is broken WRT memory management and clone IntQueue is history. Please run 'make realclean; perl Configure.pl; make -s' to get pmc class enums reordered. leo
Re: Roll Call
Better late then never...count me in. Michael Lazzaro wrote: This message is to open the perl6-documentation list. First things first, can we get a quick roll call of who is interested in this effort, at least in abstract principle? No point in having discussions unless/until there is a critical mass here. If you wish to take part in the discussions (or even just lurk), please reply to this message. If you have any particular goals that you feel this list should be addressing, please let us know. MikeL
Re: Roll Call
I think tutorials and code samples are a good start, especially to get started. In addition a reference manual (list) of builtins for quick lookups like perfunc would be helpful too. I like Rex's all-in-one reference guide http://www.rexswain.com/perl5.html And perldoc.com for a more comprehensive reference resource ;)~ -Carlos Luke Palmer wrote: Date: Fri, 8 Nov 2002 16:44:48 -0600 Cc: [EMAIL PROTECTED] Content-Disposition: inline From: Allison Randal <[EMAIL PROTECTED]> Luke Palmer wrote: Yeah. I like that the best. Have a big bunch of small to medium sized POD pages, cross-reference them together, and convert them to web, texinfo, man, and all of that. Extensions? Caveats? Take a look at perldoc.com. Yep. An awful lot like that. Except smaller pages, each describing a single concept or function. Then cross-reference to related ideas. Plus tutorials and all that stuff. Luke
mem leaks test summary
After removing IntQueue this is the state of memory leaks[1] (i386/linux): Failed Test Status Wstat Total Fail Failed List of failed --- t/op/hacks.t 21 50,00% 1 t/op/rx.t237 30,43% 8-9, 12-14, 21-22 9 subtests skipped. Failed 2/35 test scripts, 94.29% okay. 8/494 subtests failed, 98.38% okay. - hacks.t uses PIO_open/PIO_new which doesn't keep track of IO objects - rx.t is broken WRT bitmaps and intstack [1] a test passes, when output matches and when it doesn't show WARNINGs/ERRORs (s. testyamd script) leo
[CVS ci] (was: Should memory be washed?)
Dan Sugalski wrote:
At 8:58 PM +0100 11/6/02, Leopold Toetsch wrote:
If we want this, then lets have Parrot_{re,}allocate{,zeroed}.
The allocate_string variants are ok with unzeroed mem already.
Which was my thought here. Things that care can ask for zeroed memory,
which they may get anyway. (Or we may keep a big pool of zeroed memory
around as it's cheaper to clean large blocks or something)
This patch implements the first step of mem alloc cleanup:
- NEW mem_sys_allocate_zeroed (calloc)
- mem_sys_allocate uses malloc now
- NEW Parrot_allocate_zeroed
- Parrot_allocate uses malloc in res_lea now
implying the following rules:
Buffer headers and such are guaranteed to be zeroed.
Mem allocated via Parrot_allocate may or may not be zeroed, depending on
allocator scheme.
The _allocate_string variants do never guarantee to deliver zeroed memory.
Next step is going through files and look, where allocating zeroed
memory looks cheaper and use mem_sys_allocate_zeroed.
leo
NULL (was Re: cvs commit: parrot interpreter.c stacks.c)
On Sat, Nov 09, 2002 at 11:09:39AM -, [EMAIL PROTECTED] wrote: > -/* Initialize the integer register chunk */ > -interpreter->ctx.int_reg_base->used = 0; > +/* Initialize the register chunks */ >interpreter->ctx.int_reg_base->free = FRAMES_PER_INT_REG_CHUNK; > -interpreter->ctx.int_reg_base->next = NULL; > -interpreter->ctx.int_reg_base->prev = NULL; By doing this you are assuming that the in memory representation of a NULL pointer is all bits NULL. This isn't guaranteed. (What *is* guaranteed by the standard is that a NULL pointer casts to 0, and that all other pointers cast to non-zero) It's not likely to be a portability problem, as I seem to remember that the C FAQ is only able to mention one very obscure platform where NULL was not all bits zero in memory. (Sorry, not online at the moment, so no URL) However, I have a niggling thought that someone telling me that some compiler product in memory leak debug mode (possibly a Microsoft compiler) was able to have NULL pointers *not* stored as all bits zero in memory, and so could fault confusion between 0 and NULL I believe that a bigger assumption (not sure if we're making it; didn't spot it) is that float 0.0 and double 0.0 are written as all bits zero in memory. Nicholas Clark -- Brainfuck better than perl? http://www.perl.org/advocacy/spoofathon/
Re: NULL (was Re: cvs commit: parrot interpreter.c stacks.c)
Nicholas Clark wrote: On Sat, Nov 09, 2002 at 11:09:39AM -, [EMAIL PROTECTED] wrote: -interpreter->ctx.int_reg_base->prev = NULL; It's not likely to be a portability problem, as I seem to remember that the C FAQ is only able to mention one very obscure platform where NULL was not all bits zero in memory. Yep C-FAQ 5.17 lists these machines (Prime50, Eclipse MV, CDC 180, old HP 3000) To NULL or not to NULL, this is the question. I believe that a bigger assumption (not sure if we're making it; didn't spot it) is that float 0.0 and double 0.0 are written as all bits zero in memory. NRegs were memset to 0, Parrot_clear_n() sets them to 0.0. But we seem to have a real problem WRT JIT and floats. Some perl6 tests still break, when run through -j. I could imagine different float formats for 80/64 bit floats is the reason. Nicholas Clark leo
RE: Initial notes
> > Should start small. No tutorials until docs & tests are done. No > working on A3 until A2 behaviors are *locked*, to whatever extent that > proves possible. > > Comments? > I think that the best way would be to create an schema of a language manual, and fill the documents as we proceed reviewing the Apocalypses. Something like this: Section 1 - Language Reference - Variables - Operators - Control flow - Subroutines - Modules - Classes - Exceptions - Regular Expressions - Extending the Perl Grammar Section 2 - Builtin Classes, Functions and Variables - Built-in Classes - Built-in Functions - Built-in Variables Section 3 - Grammar Reference Although I am probably forgetting half a dozen language features.. Could someone with more taste propose a more sound structure? -angel
Re: Initial notes
Michael Lazzaro wrote: Here's some notes based on the first bits of feedback -- something to throw rocks at, as it were. "The overall project goal is to produce documentation that will:" (1) define precise semantics for the Perl6 language; discover and document ambiguous possible behaviors and report them to the design team (Allison, Dan, Damian, Larry) for review and decisions. (2) provide detailed test cases allowing Perl6 implementors and the QA team to verify functionality as it is written. (3) encourage community interest and participation in Perl6, growing the community and the manpower available to implement the language. I think we need to allow some sections to be the definitive documentation, and others to be 'user-contributed' and rather looser later on in the project, possibly with some of the examples getting pulled in to the formal docs if appropriate. (4) be distributed, when complete, as the user documentation for Perl 6.0. Note that we have things here with quite divergent intended audiences. Not saying that's a problem, just pointing it out. :-) How (if at all) does this project link into the internal documentation of the coding team ? It would be nice to be consistent, and allow the links to work across that boundary if possible. Maybe a well developed system would encourage the coders to add more comments into the code than they do currently. [...] Should start small. No tutorials until docs & tests are done. No working on A3 until A2 behaviors are *locked*, to whatever extent that proves possible. I agree strongly on the focus, but presumably the mechanism to manage the above pages, etc. will be done early on ? R. -- Richard Nuttall
Re: Roll Call
Michael Lazzaro writes: > This message is to open the perl6-documentation list. First things > first, can we get a quick roll call of who is interested in this > effort, at least in abstract principle? No point in having > discussions unless/until there is a critical mass here. > > If you wish to take part in the discussions (or even just lurk), > please reply to this message. If you have any particular goals that > you feel this list should be addressing, please let us know. Well, I'll probably be mostly lurking and summarizing every week. -- Piers "It is a truth universally acknowledged that a language in possession of a rich syntax must be in need of a rewrite." -- Jane Austen?
Re: Initial notes
On Fri, Nov 08, 2002 at 06:50:03PM -0800, Michael Lazzaro wrote: > Conversations on this mailing list are going to look a lot like > perl6-language, except more aggressively focused on one narrow area at a > time. Starting from data types & behaviors, moving on to operators, > then blocks, conditionals, etc, then regexen. > > Should start small. No tutorials until docs & tests are done. No > working on A3 until A2 behaviors are *locked*, to whatever extent that > proves possible. Starting small sounds like a good idea. I'm not so sure about trying to "lock things down" before moving on. I don't think that will be possible in any meaningful way. The problem with trying to lock things down is that the design team are refining the design as they go. If something isn't working they change it. I will be happy to be proved wrong about this but I have a feeling that too much attention to detail will get us bogged down. andrew -- Gemini: (May 21 - June 21) Americans from coast to coast will be transfixed by your new signature dance, the Oh My God, Get It Off Me, Sweet Jesus, It Burns.
Re: Initial notes
On 9 Nov 2002 at 18:56, Andrew Wilson wrote: > Starting small sounds like a good idea. I'm not so sure about trying to > "lock things down" before moving on. I don't think that will be > possible in any meaningful way. The problem with trying to lock things > down is that the design team are refining the design as they go. If > something isn't working they change it. > > I will be happy to be proved wrong about this but I have a feeling that > too much attention to detail will get us bogged down. I also think that we shouldn't try to provide too exact and final documentation at once. Just define each area "with enough detail" (whatever that means) and then move on. Until whole language-design is somewhat complete, there will be things which requires earlier decisions to be changed. -- Markus Laire 'malaire' <[EMAIL PROTECTED]>
Internals Docs (was Re: Initial notes)
Richard Nuttall wrote: > > Michael Lazzaro wrote: > > >Here's some notes based on the first bits of feedback -- something to > >throw rocks at, as it were. > > > > > >"The overall project goal is to produce documentation that will:" > > > >(1) define precise semantics for the Perl6 language; discover and > >document ambiguous possible behaviors and report them to the design team > >(Allison, Dan, Damian, Larry) for review and decisions. > > > >(2) provide detailed test cases allowing Perl6 implementors and the QA > >team to verify functionality as it is written. > > > >(3) encourage community interest and participation in Perl6, growing the > >community and the manpower available to implement the language. > > > How (if at all) does this project link into the internal documentation > of the coding team ? > It would be nice to be consistent, and allow the links to work across > that boundary > if possible. I think we should probably have them suggest an approach to us... obviously, most of the internal documentation can best be handled by the people coding it, as long as they remember to do it. :-) So I'm not sure of where the line is there, in terms of what might be helpful to them, and what might not be. The only thing I've been hearing most resoundingly from them is that they want test cases. That's probably something we can do well, if we're writing the documentation for a section and the tests that verify that functionality at the same time. If any perl6-internals people here have suggestions or requests, please let us know. MikeL
Re: Initial notes
Markus Laire wrote: > On 9 Nov 2002 at 18:56, Andrew Wilson wrote: > > I will be happy to be proved wrong about this but I have a feeling that > > too much attention to detail will get us bogged down. > > I also think that we shouldn't try to provide too exact and final > documentation at once. Just define each area "with enough detail" > (whatever that means) and then move on. Until whole language-design > is somewhat complete, there will be things which requires earlier > decisions to be changed. My feelings are mixed. I don't think we need to fill _every_ hole in exact sequence. But I'd like to be as precise and ordered as possible, because I think that's where this group can contribute to the effort: by filling in the details, or encouraging the designers to do it. If we keep the basic needs in mind, we should be fine: -- We should be making sure nothing nasty gets missed. The nightmare scenario is if very basic assumptions need to be revisited a year or two after the fact, because of some "oops" in the details that has a cascading effect through the entire design. -- In order to be useful to the internals team, we have to specify primitive, narrow behaviors wherever possible, as soon as possible. If the details specify something they weren't originally counting on, it can blow large sections of their code away in trying to meet the new expectations. I think we've all been there before. 8-( Don't know -- we'll just have to play it by ear. The primary thing I *don't* want is for this to be a clone of perl6-language, where umpteen people are asking umpteen different, unrelated questions, and there's no particular motivation to see any of the details through. That would make it impossible to make useful progress on documenting anything. So I think the one place we _do_ need to be fairly hard-nosed is in focusing the discussion on only a few topics at a time, and politely directing other questions to perl6-language if we're not prepared to deal with them yet. MikeL
Re: Roll Call
Carlos Ramirez wrote: > I like Rex's all-in-one reference guide > http://www.rexswain.com/perl5.html > > And perldoc.com for a more comprehensive reference resource ;)~ It's true, I use perldoc all the time. :-) Beats trying to "less" through the man pages by a wide shot. Let me ask you, Carlos -- if you could have the people to rebuild perldoc from the ground up, what changes would _you_ want to make? Is there anything that still drives you nuts? MikeL
Re: Initial notes
Angel Faus wrote: Should start small. No tutorials until docs & tests are done. No working on A3 until A2 behaviors are *locked*, to whatever extent that proves possible. Comments? I think that the best way would be to create an schema of a language manual, and fill the documents as we proceed reviewing the Apocalypses. Something like this: Section 1 - Language Reference - Variables - Operators - Control flow - Subroutines - Modules - Classes - Exceptions - Regular Expressions - Extending the Perl Grammar Section 2 - Builtin Classes, Functions and Variables - Built-in Classes - Built-in Functions - Built-in Variables Section 3 - Grammar Reference Although I am probably forgetting half a dozen language features.. Could someone with more taste propose a more sound structure? -angel I think thats a good idea, and so, on a whim, I fleshed out your skeleton a little bit, and tossed in a few more ideas: Section 1 - Language Reference - Variables - Scoping - Default Attributes - Globals - Default Variables ($_,@_,$^a,etc) - Operators - Precedence - Superpositional - Vectorizing - Control flow - Loops - Continuations - Exceptions - Subroutines - Default Attributes - Default Arguments - Coroutines - Closures - Builtin Functions - Modules - Using Modules - Importing and Exporting - Symbol Table (%MY and %OUR) - Classes - Inheritance - Defining Attributes - Overloading Operators - User-Defined Operators - Builtin Classes - Regular Expressions - Grammars - perlre for Perl6 - Possible Other Stuff I forgot. Section 3 - Grammar Reference - Extending the Perl Grammar Section 4 - Core Modules Section 5 - Migrating from Perl 5 Section 6 - PerlFAQ I'm sure I forgot all sorts of stuff, as this was just off the top of my head.
Re: Initial notes
On Sat, Nov 09, 2002 at 04:49:42PM -0500, Joseph F. Ryan wrote: > Angel Faus wrote: >> I think that the best way would be to create an schema of a language >> manual, >> and fill the documents as we proceed reviewing the Apocalypses. >> >> Something like this: >> >> Section 1 - Language Reference >> - Variables >> - Operators >> - Control flow >> - Subroutines >> - Modules >> - Classes >> - Exceptions >> - Regular Expressions >> - Extending the Perl Grammar >> >> Section 2 - Builtin Classes, Functions and Variables >> - Built-in Classes >> - Built-in Functions >> - Built-in Variables >> >> Section 3 - Grammar Reference >> >> Although I am probably forgetting half a dozen language features.. Could >> someone with more taste propose a more sound structure? >> >> -angel >> > I think thats a good idea, and so, on a whim, I fleshed out your skeleton a > little bit, and tossed in a few more ideas: > > > Section 1 - Language Reference > - Variables > - Scoping > - Default Attributes > - Globals > - Default Variables ($_,@_,$^a,etc) Topic needs to go somewhere but can we talk about it here without mentioning anything that sets up a topic? We need to talk about references and dereferencing. perl 6 will do a lot of dereferencing automatically but we still need to explain what's going on. > - Operators > - Precedence > - Superpositional These are now called Junks (From Junctions) > - Vectorizing Smart match (not sure if it belongs here we really need to have mentioned Regexps before we cover it in depth). > - Control flow > - Loops > - Continuations > - Exceptions if, unless, given, when, try, and all the new BLOCK thingies (PRE, POST, LAST etc.) > - Subroutines > - Default Attributes > - Default Arguments > - Coroutines > - Closures > - Builtin Functions > - Modules > - Using Modules > - Importing and Exporting > - Symbol Table (%MY and %OUR) > - Classes > - Inheritance > - Defining Attributes > - Overloading Operators > - User-Defined Operators > - Builtin Classes > - Regular Expressions > - Grammars > - perlre for Perl6 > - Possible Other Stuff I forgot. Input/Output Filehandles Dirhandles IPC (threads & forks) > Section 3 - Grammar Reference > - Extending the Perl Grammar > > Section 4 - Core Modules > > Section 5 - Migrating from Perl 5 > > Section 6 - PerlFAQ > > I'm sure I forgot all sorts of stuff, as this was just off the top of my > head. andrew -- Cancer: (June 22 - July 22) Someday, you'll look back on all of this and laugh very, very bitterly. msg23864/pgp0.pgp Description: PGP signature
Re: Initial notes
On Sat, 09 Nov 2002 13:21:06 Michael Lazzaro wrote: >Markus Laire wrote: >> On 9 Nov 2002 at 18:56, Andrew Wilson wrote: >> > I will be happy to be proved wrong about this but I have a feeling that >> > too much attention to detail will get us bogged down. >> >> I also think that we shouldn't try to provide too exact and final >> documentation at once. Just define each area "with enough detail" >> (whatever that means) and then move on. Until whole language-design >> is somewhat complete, there will be things which requires earlier >> decisions to be changed. > >My feelings are mixed. I don't think we need to fill _every_ hole in >exact sequence. But I'd like to be as precise and ordered as possible, >because I think that's where this group can contribute to the effort: by >filling in the details, or encouraging the designers to do it. If we >keep the basic needs in mind, we should be fine: > >-- We should be making sure nothing nasty gets missed. The nightmare >scenario is if very basic assumptions need to be revisited a year or two >after the fact, because of some "oops" in the details that has a >cascading effect through the entire design. > >-- In order to be useful to the internals team, we have to specify >primitive, narrow behaviors wherever possible, as soon as possible. If >the details specify something they weren't originally counting on, it >can blow large sections of their code away in trying to meet the new >expectations. I think we've all been there before. 8-( > >Don't know -- we'll just have to play it by ear. The primary thing I >*don't* want is for this to be a clone of perl6-language, where umpteen >people are asking umpteen different, unrelated questions, and there's no >particular motivation to see any of the details through. I've become convinced that one of the most important things we can do is produce test cases - when showing something to a programmer, their gonna want working code. In P6L we bandy about questionable code all the time. What should be done is that once this questionable code has a defined behavior it should be turned into a test and put whereever it needs to go. If the test is well documented, we have clear documentation AND an automatic wy of testing our implementation - ie run the tests. The next big advantage of tests is that we can catch contradictions or snags with decisions made weeks or months apart, in an automatic way. Writing tests for all these behaviors has the side effect of making us experienced Perl 6 programmers before the language is finished. Definitely an edge in the job market :-) -Erik That would >make it impossible to make useful progress on documenting anything. So >I think the one place we _do_ need to be fairly hard-nosed is in >focusing the discussion on only a few topics at a time, and politely >directing other questions to perl6-language if we're not prepared to >deal with them yet. > >MikeL > Get 25MB of email storage with Lycos Mail Plus! Sign up today -- http://www.mail.lycos.com/brandPage.shtml?pageId=plus
Re: Initial notes
"Joseph F. Ryan" wrote:
> Angel Faus wrote:
> >I think that the best way would be to create an schema of a language manual,
> >and fill the documents as we proceed reviewing the Apocalypses.
Agreed -- we should certainly figure out the overall structure first,
before doing much else. I think that's a pretty good start for an
outline, too.
Now given our intended goal of it being detailed enough for internals,
but written even for beginners, how do we "package" the materials?
(Should it be a concise language reference, a series of tutorials, a
formal or informal booklike document that explains everything in detail?
I know, I know, everyone's going to say "yes, all of them, and it
should dispense softdrinks from your CD-ROM drive upon request...")
We need a consensus, or at least a better argument ("booklike" currently
leads, but not in a statistically significant way.)
Thinking aloud:
We want the Perl community to grow. So how will newcomers to Perl6
learn about the language? That's a _really_ tough question, but I'm
willing to bet it's typically something like this:
When people first get an interest in Perl, they visit the online docs to
try and see what it's like. Then if they read through the initial stuff
and _still_ like Perl :-) they'll go out and buy a book or two on the
subject, which they will study. Once they get familiar with the
language, they'll go buy another few more specialized books, according
to their interest.
So it's the online docs that make-or-break that first decision --
whether to invest any time or money in learning Perl at all. If they
can't understand or don't like the basics of Perl from reading the
online docs, it will be harder to motivate them to pay for $50 books on
the subject, free software or not. It's just like any big decision: we
need to quickly build their confidence that they're dealing with
something they'll enjoy working with. If we can't, we lose them before
they even get to the bookstore, much less do any significant programming.
So what constitutes a "buy" decision for those potential Perl customers?
What would potential converts most want to see? A simple structure,
perhaps beginner-level things broken out from the advanced-level things?
Actual tutorials, or just really good explanations with examples? What
would get them to the next step -- the bookstore?
We can make some guesses based on our own experiences, and they might be
close, except that I think we are a profoundly self-selected group.
There may be some knowledgeable people we can ask this of, given our
connections (and the fact that as Perl grows, so do the markets of
companies that teach and document Perl.)
We might also want to put the question to the Perl public, in terms of
some quick online research (a questionnaire) -- Piers could announce it
in his summary, which would get us probably between 500-1000 responses.
(Still self-selected, but not nearly as bad.)
MikeL
--- P.S: ---
After users gain some experience, the role of the online/manpage
documentation shifts to one of "support". People will go to the docs if
any of these is true:
-- they have a very specific question
-- they have a very advanced question
-- they have a question their book(s) don't answer
-- they don't know enough about their question to know where to look for
it in the book.
The role of the docs then is to provide easy-to-find answers to a user's
questions. They will be "easy-to-find" if the site has been constructed
such that they've already learned where to find everything, when first
visiting the site on their initial "scouting missions."
MikeL
Re: Initial notes
Joseph F. Ryan writes: Siction 0 : General concepts . ( this is usually the most difficult part of a rich language ( and perl5 / perl6 ) compile-phase / run-phase / more ??? many more... all things that we will be back-referencing all the time. may be this is just good glossary. (It seems that we just have to build a good consistent glossary of things perl6-language is talking about. ) > Section 1 - Language Reference > - Variables i) $thing @thing %thing &thing - variable name vs "variable container" vs value ( ~as in M Lazarro's Intro ) - properites as concept ; run-time and copile-time > - Globals - Lexicals - temp , let > - Scoping - Context - assignment and binding . This is here because although they are operators , they are very intimate to the whole structure of the language . - how props ( run-time / compile-time ) behave under = and := > - Default Attributes ( default properties ?? ) > - Default Variables ($_,@_,$^a,etc) this have to be explained together with concepts they are here to support : $_ <-> topicalizers ; @_ <-> sub signatures ; $^_ <-> curring so probably not here > - Operators > - Precedence > - Superpositional > - Vectorizing > - Control flow > - Loops > - Continuations > - Exceptions > - Subroutines > - Default Attributes > - Default Arguments > - Coroutines > - Closures > - Builtin Functions > - Modules > - Using Modules > - Importing and Exporting > - Symbol Table (%MY and %OUR) > - Classes > - Inheritance > - Defining Attributes > - Overloading Operators > - User-Defined Operators > - Builtin Classes > - Regular Expressions > - Grammars > - perlre for Perl6 > - Possible Other Stuff I forgot. > > Section 3 - Grammar Reference > - Extending the Perl Grammar > > Section 4 - Core Modules > > Section 5 - Migrating from Perl 5 > > Section 6 - PerlFAQ > > I'm sure I forgot all sorts of stuff, as this was just off the top of my > head. > > > arcadi
Re: Initial notes
Michael Lazzaro wrote: "Joseph F. Ryan" wrote: Angel Faus wrote: I think that the best way would be to create an schema of a language manual, and fill the documents as we proceed reviewing the Apocalypses. Agreed -- we should certainly figure out the overall structure first, before doing much else. I think that's a pretty good start for an outline, too. Now given our intended goal of it being detailed enough for internals, but written even for beginners, how do we "package" the materials? (Should it be a concise language reference, a series of tutorials, a formal or informal booklike document that explains everything in detail? I know, I know, everyone's going to say "yes, all of them, and it should dispense softdrinks from your CD-ROM drive upon request...") I think the biggest concern should be converts from perl 5. Most people will have an attitude similar to: "I know how to do X in perl5, now how do I do that in perl6?" I think that a set of tutorials (that refer to the main docs many, many times) that show how to translate common idioms, structures, and techniques from perl 5 to perl 6, such that if a person reads through them, they'll at least have enough knowledge on perl6 to begin to write in it, and know where to turn to when they have problems. After users gain some experience, the role of the online/manpage documentation shifts to one of "support". People will go to the docs if any of these is true: -- they have a very specific question -- they have a very advanced question -- they have a question their book(s) don't answer -- they don't know enough about their question to know where to look for it in the book. I think that most people first go to a "support place", i.e. PerlMonks, Perlguru, #perl, c.l.p.m, etc., where the people there will refer them to the correct docs. Joseph F. Ryan [EMAIL PROTECTED]
Re: Initial notes
Hi, Michael, I personally like perldoc.com documentation . I think that for now we do not need a comrehensive reference. we just need a series of more or less connected and ( not to be afraid if ) overlapping esseis on particular topic with many code examples which may be after collected ( in orginized way , or be referenced ) to become tests . I agree , we need to have a general "structure" of the language . and essays "filling" the entries in it. Like in perldoc.com , for each concept or several related concepts there may be a "overview - type" essay , a "beginner" level , a "comprehensive" and maybe one full of questions that we asked or we think would be useful to ask on that topic. FAQ's are very usefull. so something like FAQ section in each essay. E.g. I think your /var.html introduction is too large and it would be good to break it in peaces. which can grow up afterwards. arcadi.
Re: Initial notes
[EMAIL PROTECTED] wrote: Joseph F. Ryan writes: Siction 0 : General concepts . ( this is usually the most difficult part of a rich language ( and perl5 / perl6 ) compile-phase / run-phase / more ??? ...many more... all things that we will be back-referencing all the time. may be this is just good glossary. Well, I wrote a basic compile-time overview doc for parrot/languages/perl6 awhile ago; even though it is now out-of-date, it should still be of some use. As far as runtime is concerned, that's parrot's job to document ;)
Re: Initial notes
> Mailing-List: contact [EMAIL PROTECTED]; run by ezmlm > Date: Sat, 9 Nov 2002 22:24:20 + > From: Andrew Wilson <[EMAIL PROTECTED]> > > > - Operators > > - Precedence > > - Superpositional > > These are now called Junks (From Junctions) Iie, these are now called "Junctions" (From Junctions). Larry's "junk" was just a joke. > > - Vectorizing > > Smart match (not sure if it belongs here we really need to have > mentioned Regexps before we cover it in depth). Smart match does belong here. There's a lot more to it than just regexen now. > > - Control flow > > - Loops > > - Continuations > > - Exceptions > > if, unless, given, when, try, and all the new BLOCK thingies (PRE, POST, > LAST etc.) =20 Right. Modified: - Control flow - Closures (*) - Conditionals <> - Loops<> - Exceptions <> (*) If we explain this here, it could lead to a clearer understanding of what follows. But, for an avanced concept, it may not be good to explain before familiarity with what follows. I'd suggest putting this off until one of those "Oh! THAT'S what's happening!" sections. > > - Subroutines > > - Default Attributes > > - Default Arguments > > - Coroutines > > - Closures > > - Builtin Functions > > - Modules > > - Using Modules > > - Importing and Exporting > > - Symbol Table (%MY and %OUR) > > - Classes > > - Inheritance > > - Defining Attributes > > - Overloading Operators > > - User-Defined Operators > > - Builtin Classes > > - Regular Expressions > > - Grammars > > - perlre for Perl6 > > - Possible Other Stuff I forgot. > > Input/Output > Filehandles > Dirhandles > IPC (threads & forks) Luke
Re: Initial notes
> Mailing-List: contact [EMAIL PROTECTED]; run by ezmlm > Date: Sat, 09 Nov 2002 14:43:42 -0800 > From: Michael Lazzaro <[EMAIL PROTECTED]> > We can make some guesses based on our own experiences, and they might be > close, except that I think we are a profoundly self-selected group. > There may be some knowledgeable people we can ask this of, given our > connections (and the fact that as Perl grows, so do the markets of > companies that teach and document Perl.) > > We might also want to put the question to the Perl public, in terms of > some quick online research (a questionnaire) -- Piers could announce it > in his summary, which would get us probably between 500-1000 responses. > (Still self-selected, but not nearly as bad.) > > MikeL I teach Perl to sortof-programmers now, which, I imagine, is a lot of our audience. I've found it works very well to explain in terms of C (despite how much Perl is diverging from C). I guess when people see the samples they'll make the connection fairly quickly. But my point is that we shouldn't necessarily start too simply. Use without definition of words like "block" and "expression" should not be a problem. Of course, a glossary is always nice. A cross-referenced glossary is extra nice. Luke
Re: Initial notes
> Mailing-List: contact [EMAIL PROTECTED]; run by ezmlm > Date: Sat, 09 Nov 2002 19:20:58 -0500 > From: "Joseph F. Ryan" <[EMAIL PROTECTED]> > X-Accept-Language: en-us, en > Cc: [EMAIL PROTECTED] > X-SMTPD: qpsmtpd/0.12, http://develooper.com/code/qpsmtpd/ > > Michael Lazzaro wrote: > > >"Joseph F. Ryan" wrote: > > > > > >>Angel Faus wrote: > >> > >> > >>>I think that the best way would be to create an schema of a language manual, > >>>and fill the documents as we proceed reviewing the Apocalypses. > >>> > >>> > > > > > >Agreed -- we should certainly figure out the overall structure first, > >before doing much else. I think that's a pretty good start for an > >outline, too. > > > >Now given our intended goal of it being detailed enough for internals, > >but written even for beginners, how do we "package" the materials? > >(Should it be a concise language reference, a series of tutorials, a > >formal or informal booklike document that explains everything in detail? > > I know, I know, everyone's going to say "yes, all of them, and it > >should dispense softdrinks from your CD-ROM drive upon request...") > > > > I think the biggest concern should be converts from perl 5. Most people > will > have an attitude similar to: "I know how to do X in perl5, now how do I do > that in perl6?" I think that a set of tutorials (that refer to the main docs > many, many times) that show how to translate common idioms, structures, and > techniques from perl 5 to perl 6, such that if a person reads through them, > they'll at least have enough knowledge on perl6 to begin to write in it, and > know where to turn to when they have problems. I disagree. Perl 6 is so different from Perl 5 in its core that I think people will benefit just as much from learning from the top as they will from learning in terms of Perl 5. The specific docs on C, etc. will be enough to answer the aforementioned question; i.e. the example code will be sufficient. To clarify, Perl 6 isn't that different in its syntax, but it's very different in its ideas. For the "quick fix" type (how do I do a C-style for loop?), they don't need to know the new concepts of "blocks are just functions with closures as arguments." But if they want to, it will probably be easier not to explain in terms of Perl 5. Luke
Re: Initial notes
"Joseph F. Ryan" wrote: > I think the biggest concern should be converts from perl 5. Most people > will Should we be focus on converting perl5 people, or converting people completely new to Perl? My hope is that perl5 folks won't need much convincing -- perhaps a tutorial/summary of changes -- whereas Perl has gotten a *bad* reputation from outsiders, who say the language is completely incomprehensible. In other words, do you think we're going to have an issue with Perl5 converts big enough to require them to have documentation tailored to them explicitly (as opposed them using the normal "beginner" stuff?) I don't know the answer, but I know what I'm hoping it will be. MikeL
Re: Initial notes
> -- whereas Perl has > gotten a *bad* reputation from outsiders, who say the language is > completely incomprehensible. To clarify: Perl5 has gotten quite a bit of flak for being opaque, write-only-read-never, whatever they want to call it. I am not _agreeing_ with these statements, nor should we argue whether or not they have merit. It's irrelevant. The only useful data point is that the statements _are_ being made, and that they are widespread. That points to a market problem that we must address if Perl6 is going to achieve substantial popularity: the issue of better introducing newcomers to the language, and reducing the learning curve *very significantly*. That, in turn, implies significant changes to the documentation strategy of Perl5, because Perl6 is going to be an even more complex language. As difficult as it may be, we need to document Perl6 from the standpoint of people who don't know it, who have never used Perl before, and are quite possibly profoundly stupid. MikeL
Re: Initial notes
> Then if they read through the initial stuff and _still_ like Perl :-) > they'll go out and buy a book or two on the subject, which they will > study. Once they get familiar with the language, they'll go buy > another few more specialized books, according to their interest. I wouldn't bank too much on this behaviour outside a handful of countries. there are people who get paid a month those $35 The Camel costs. ok, maybe two handfuls. flaviu
Autovivification
I was writing up some docs (in a perldoc-like style--we can always
change the form later, but the content is important), and started
working on documenting references. I ended up with this bit:
*** BEGIN DOCS ***
=head3 Autovivification
Actually, one of the features of the extra-sigil mentioned earlier makes
this line of code unnecessary. If you use the extra-sigil syntax and
the scalar used is C, it's automatically filled in with a
reference of the appropriate type. This process is called
I.
So the first (incorrect) example can be fixed by just changing the
C line to this:
@{%anagrams{$key}}.push $word;
Autovivification also happens when you try to retrieve or set an element
of an array or hash reference, but the reference is C:
$undefined_var[$idx]=$scalar;
*** END DOCS ***
Is this correct? My rationale is that other classes could have a
C method, so you can't infer just from the C that you should
autovivify an array.
--Brent Dax <[EMAIL PROTECTED]>
@roles=map {"Parrot $_"} qw(embedding regexen Configure)
Wire telegraph is a kind of a very, very long cat. You pull his tail in
New York and his head is meowing in Los Angeles. And radio operates
exactly the same way. The only difference is that there is no cat.
--Albert Einstein (explaining radio)
Re: Autovivification
Brent Dax wrote:
>
> I was writing up some docs (in a perldoc-like style--we can always
> change the form later, but the content is important), and started
> working on documenting references. I ended up with this bit:
I imagine (if there are no objections) that the general perldoc writing
style (booklike, informal) is probably exactly what we want, yes? We'll
just break it up into *much* smaller individual sections, so that only
one concept is being taught at a time. Probably.
> =head3 Autovivification
> @{%anagrams{$key}}.push $word;
> $undefined_var[$idx]=$scalar;
Hmm, not a clue. I could argue that one both ways. Perhaps (thinking
aloud) they only autovivify if you've explicitly called out the exact
type they store, but otherwise generate an exception? (Because it seems
like the behavior would be _very_ handy if you wanted it, and a real
pain in the $#@ when you invoked it unintentionally.)
So maybe if you previously declared them like this:
my \Array %anagrams;
my \Array $undefined_var;
you'd get autovivifying behavior (but what the heck is the syntax for
"stores a reference to an Array"? The above doesn't seem bad, but I'm
just guessing.)
but if you declared them like this:
my %anagrams;
my $undefined_var;
you wouldn't, because it would be "too ambiguous" (for the programmer,
not the compiler. :-)
Of course, this problem is closely related to the problem of determining
whether any arbitrary object autovivifies:
my MyObj $obj = undef;
$obj.foo();
I'd argue that if the first example autovivifies, this one should
too. (And yes, I realize we're using the term in a not-strictly-Perl5 way.)
MikeL
RE: Autovivification
Michael Lazzaro:
# Brent Dax wrote:
# >
# > I was writing up some docs (in a perldoc-like style--we can always
# > change the form later, but the content is important), and started
# > working on documenting references. I ended up with this bit:
#
# I imagine (if there are no objections) that the general
# perldoc writing style (booklike, informal) is probably
# exactly what we want, yes? We'll just break it up into
# *much* smaller individual sections, so that only one concept
# is being taught at a time. Probably.
OK. I'm trying to do that in the stuff I'm writing.
# > =head3 Autovivification
# > @{%anagrams{$key}}.push $word;
# > $undefined_var[$idx]=$scalar;
#
# Hmm, not a clue. I could argue that one both ways. Perhaps (thinking
# aloud) they only autovivify if you've explicitly called out
# the exact type they store, but otherwise generate an
# exception? (Because it seems like the behavior would be
# _very_ handy if you wanted it, and a real pain in the $#@
# when you invoked it unintentionally.)
#
# So maybe if you previously declared them like this:
#
#my \Array %anagrams;
#my \Array $undefined_var;
I think that, if Perl can determine the type with virtually no
ambiguity, it should autovivify. In this case, since we know they
wanted an array (they used the @ explicitly), we'll autovivify an array.
(I say "virtually no" because one could make the argument that you don't
know if we wanted a standard array or a typed one.)
--Brent Dax <[EMAIL PROTECTED]>
@roles=map {"Parrot $_"} qw(embedding regexen Configure)
Wire telegraph is a kind of a very, very long cat. You pull his tail in
New York and his head is meowing in Los Angeles. And radio operates
exactly the same way. The only difference is that there is no cat.
--Albert Einstein (explaining radio)
