Re: proposal: 404 method
On Mon, 20 Jun 2005, BÁRTHÁZI András wrote: Hi, > Is there a way, to catch, if I call a method, that doesn't exists, to run > a default one? I'm thinking about an "error handler" method. See all the AUTO subs. Cool! Where? Is it working currently with Pugs? Synposis 10... abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: proposal: binding with a function
On Mon, 20 Jun 2005, BÁRTHÁZI András wrote: Hi, I'm still interested in, why "alias" wouldn't be a native Perl 6 term? I think, there are several reasons for "alias": I am not arguing against alias, but just wanted to point out something. - in Perl 6, currently there's no way to create a reference to a variable, _with the context of the variable_, too unless you bind immediately where you declare the original variable: Some new examples, maybe better than before: sub kilobytes ($value:) is export { return $value*1024; } alias kilobytes, kilobyte; replace the last line with: &kilobytes := &kilobyte; and the scoping is not an issue. And with synonyms, binding as soon as declaring seems prudent. --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Ignoring parameters
On Sat, 18 Jun 2005, Damian Conway wrote: John Siracusa wrote: (BTW, I'm not sure where those "./" thingies came from, but it's what GMail showed in your message. I'm assuming it should just be ".") No. There's now also a unary ./ operator in Perl 6. Unary . calls a specified method on the current topic. Unary ./ calls a specified method on the current invocant. The point being that methods no longer topicalize their invocant. So you need to use ./ instead of . to call methods on an implicit invocant. Er, is it true that methods don't topicalize the invocant nowadays? I had thought that they do and one needs the ./ to still talk about the invocant if some inner loop stole the $_, and until such stealing occurs .foo() and ./foo() are the same... --abhijit Damian Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: ./method
On Sun, 15 May 2005, Juerd wrote: I do think $__ looks too much like $_. Yeah, lets drop that idea. A bit better would be to not have a "bigger" topic, but a "higher" topic, $-, but the problem with seeing the invocant as a topic on another level, is that inconsistency/asymmetry would be introduced between method { # topic is object given 5 { # topic is 5 # "bigger" topic is object, we access it as $__ } } and given $object { # topic is object given 5 { # topic is 5 # $object is neither $_ nor $__ } } By "bigger topic" I did not mean "outer topic"; I was thinking that $__ can *only* get bound to an invocant. You didn't say what you think about ./method; What is your opinion? I like it. ( I assume you mean: .method is always $_.method ./method is always $?SELF.method ) Yes, I like it a lot! --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: ./method
(Note that "./" and "../" are prefix operators, and unlike ".?", ".*", ".+" and ".=", cannot be used infix. In fact, it requires that "?", "*", "+" and "=" be thought of as meta-operators to ".", and from now on, to "./" and "../" as well, so you get "./+method". This isn't as complex as it looks right now.) Your opinions please! (I ask those who already responded off-list, to repeat their opinion here) Since new syntax is being suggested for these things, here is my suggestion, very late in the discussion, but here it is anyway. $_ is the topic; the "only" problem is that we have two topics here: an immediate and a "main" topic. What if a method call binds the invocant to *both* $_ and the "bigger topic" $__? method foo($x){ # invocant accessible by both $__ and $_ for (1..3) { # invocant accessible by $__ only .bar(); # called on $_ $__.bat(); # called on the invocant $?CLASS.bas(); } } I like this because things still look a little like a topic. This is not better than $o/$O, except that $__ looks more like $_ (but maybe it looks too much like $_, and that alone could invalidate this proposal). Comments? --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Junctions of classes, roles, etc.
On Mon, 2 May 2005, [ISO-8859-1] Thomas Sandlaß wrote: David Storrs wrote: Tell me what this does: class Tree { method bark() { die "Cannot instantiate a Tree--it is abstract!" } } class Birch { method bark() { return "White, papery" } } class Oak { method bark() { return "Dark, heavy" } } class Dog { method bark() { print "Woof, woof!"; return "bow wow" } } Four 'pure' classes so far. class AlienBeastie isa Tree isa Dog {} Here you get an error/warning of a composition time conflict between &Tree::bark and &Dog::bark. I don't think so; I had come to the same conclusion before realising that we are talking inheritance here, not roles. So no trouble at class composition time. Superclasses do not enter the picture while composing. You'd be right if s/isa/is/ and then s/is/does/, of course. When you dispatch, what happens would depend upon WALKMETH (according to the pseudocode for CALLONE in A12). Usually the first inherited method would get called. TSa (Thomas Sandlaß) regards, abhijit
Re: Junctions of classes, roles, etc.
On Sat, 30 Apr 2005, Aaron Sherman wrote: On Sat, 2005-04-30 at 22:24 +0800, Autrijus Tang wrote: On Sat, Apr 30, 2005 at 09:13:26AM -0500, Abhijit Mahabal wrote: I do not see how any auto-threading occurs in that code. It is completely innocuous in that sense, and I don't think that is what horrified David. What was troublesome was, I think: my Str|Int $x; $x.foo(); # runs two methods and returns a junction That would be absolutely horrible. Then tell me what $!.can("chars") returns, assuming that $! is implemented as an "any" junction of Int and Str values? If $! were explicitely "Yes"|1, then I agree that it returns false|true. I believe that in the code you wrote.. $x = ::("Int") | ::("Str") my ::($x) $y; $x is a junction, and $y is not a junction. "type", to me, is just a sticky note attched to an object. I would not like to see autothreading on every junctive sticky. In the code above, if there were a method called .type(), then $y.type() would indeed return a junction, but not by running two methods and orring their output. Str|Int is simply the type of "Yes"|1, isn't it? Hmmm... I am not sure. Maybe the type is just "Junc" or something. Str|Int is also the type of 7 and of "yes". Moreover, if the return type of a method is junctive, would you want that menthod to autothread too? --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Junctions of classes, roles, etc.
On Fri, 29 Apr 2005, Brent 'Dax' Royal-Gordon wrote: David Storrs <[EMAIL PROTECTED]> wrote: On Thu, Apr 28, 2005 at 03:28:41PM +0200, Ingo Blechschmidt wrote: so we had junctions of Code references some days ago, what's with junctions of Class and Role objects? :) Could we see some code that shows why this is a good idea? My initial reaction is horror; I can very easily see huge numbers of subtle, hard-to-reproduce bugs coming out of this. On the other hand, I do not immediately see major applications...most of what I can see is things that reduce the amount of code needed, but don't actually accomplish anything fundamentally new. What do junctions of Class|Role objects give us that can't be achieved in other ways? I'm quite willing to believe that there are such things, but I'm not coming up with them. What do you think this is? sub foo(Str | Int $bar) { ... } I believe you mean sub foo(Str^Int $bar){...} ( something that is Int or Str but not both). But that, too, just reduces the amount of code and is merely a shortcut for: multi sub(Str $bar){...} multi sub(Int $bar){...} I do not see how any auto-threading occurs in that code. It is completely innocuous in that sense, and I don't think that is what horrified David. What was troublesome was, I think: my Str|Int $x; $x.foo(); # runs two methods and returns a junction I would like to be able to read the above code to mean: type X ::= Scalar where Str|Int; my X $x; # $x = non int/non string now a runtime error $x.foo(); # no different from if you had just said my $x Feel free to tell me I am barking up the wrong tree if that is what I am doing. --abhijit
Re: Deletion of members by mixin
On Tue, 26 Apr 2005, Aaron Sherman wrote: On Tue, 2005-04-26 at 09:58, Abhijit Mahabal wrote: On Tue, 26 Apr 2005, Aaron Sherman wrote: It also might be useful for roles to be able to delete members and methods from a class like so: role foo { has $.x; has not $.y; } But that brings up the issue of who has the final authority. In class composition, a method defined in the class hides those in the roles, and in this sense it is the boss on "adding decisions". So, as you can see, in the case of mixins, the hypothetical: role z { has not mymeth; } would, in fact, remove mymeth from $x, and in class composition, it would remove the method from parents, but not from the class being declared (as it should not, by my way of thinking). Assuming that mymeth isn't AUTOMETHed, isn't that equivalent to saying: role z{ method mymeth([EMAIL PROTECTED]) {...} } Moreover, how does 'has not' work with multis? Does it clobber multi's of all signatures? what if you have something like: class A { multi method foo($x){ something } } role B { has not foo; has not die;} class C is A does B {...} # the theft of ... for real code does make writing pseudocode harder! I am just thinking aloud. I do like the proposal at least somewhat, and was wondering if it could be used as an aid in refactoring: an easy way to comment out methods to see if we have forgotten to change a call somewhere. --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Roles as anonymous and/or closures
On Tue, 26 Apr 2005, Aaron Sherman wrote: It also might be useful for roles to be able to delete members and methods from a class like so: role foo { has $.x; has not $.y; } But that brings up the issue of who has the final authority. In class composition, a method defined in the class hides those in the roles, and in this sense it is the boss on "adding decisions". I like this a lot because I think it makes it possible for me to read a class description and have a sense of what is going on. With the "has not" proposal, it seems that the role would need to be the boss on "deleting decisions". Could get pretty confusing! --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Documentary annotations: $what doc
On Thu, 31 Mar 2005, Luke Palmer wrote: Chip Salzenberg writes: I'd like to annotate Perl 6 parameters and other entities using traits, since that's the best way (I know of) to have them appear immediately in the text of the program where they are. Supposing I had a "doc" trait, could I say: sub f2c (Num $temp doc)>> doc {...} Or would I be forced to spell it doc('stuff') ? Well, first you need an `is` somewhere in there. And after that I think you'll need to do it in doc('stuff') form. If we did allow doc<>, then this: is doc But if you are going to use doc('') in a million places, can you not also make doc a trait_verb and save a little typing? So: role doc{ sub *trait_verb:doc($container: $string) { ... } } But what do I apply the role to? perhaps class Object does doc Now sub f2c (Num $temp doc "Temperature in degrees F") {...} works(I think): trait_verb:doc is a sub, not a method, and so parens are not needed. It works, but that doesn't read too well. We do need a verb there. "docs", perhaps? Or "gloss", which is both a noun and a verb? --abhijit
Re: compile time signature checking
Another edge case: is it legal to have an optional Pair in the signature? That is: sub foo($x, Pair ?$y, +$z){...} If yes, what does this parse as: foo(10, z => 5); If z => 5 is bound to $y, then $y is almost mandatory. ('almost' because we can still say foo(10); ). (and then can we also say foo(10, z => 5, z => 6)? :) That at least has the feature that it can be used to write bizarre code like C< sing :e:i:e:i:o > ) If it is bound to $z instead, how do we bind anything to $y positionally? Might as well change that to +$y. It seems to me that an optional Pair is a catastrophe waiting to happen, and maybe it should just be illegal (or produce a warning at least) Sorry if this has been gone over before... --abhijit
compile time signature checking
I was thinking about how binding of arguments to parameters in a sub/method call would happen. Seems to be a darn tricky thing with all sorts of potential pitfalls! I have a few questions. Consider the following piece of code. Are my expectations correct? sub foo($x, $y, *%slurp) { $x + $y } say "expecting 10: ", foo(3,7); say "expecting 10: ", foo(x => 3, y => 7); say "expecting 10: ", foo(y => 7, x => 3); say "expecting 10: ", foo :y<7> :x<3>; my $c = "x"; my $d = "y"; say "compile time error?: ", foo($c => 3, $d => 7); say "maybe syntax error? perhaps not ", foo :$c<3> :$d<7>; say "run time error? ", foo(x => 3, y => 7, $c => 5); Similarly, what happens here? class foo{ has $.x; method bar($.x){} # implicit *%_ } my $f = foo.new; my $c = "x"; $f.bar(10, $c => 5); # runtime error? Finally, does this also mean that defaults may not be applied until run time? For example: sub foo(?$x = 3){...} foo($c => 5); # $c may be "x", in which case default not needed. --abhijit
Re: Classes with several, mostly unused, attributes
Larry Wall wrote: On Fri, Dec 10, 2004 at 11:05:32AM -0500, Abhijit Mahabal wrote: : Consider a class (e.g., the hypothetical Geometry::Triangle) that can : have several attributes (side1, side2, side3, angle1, ang_bisector1, : side_bisector, altitude1 and so forth), most of which will not be : needed for most instances of Geometry::Triangle. This sounds to me more like a situation where you want to use mixins, if you're thinking of it as different kinds of triangles. But more likely, you just want a single private hash attribute that is manipulated by as many publicly facing methods as you like. Method declarations don't cost you anything on a per-object basis unless they're autogenerated from an attribute. But a hash attribute autovivifies just like any ordinary hash variable, and is probably clearer as well to whoever has to read your code. So, apart from declaring the methods, I just need to write .bisector1 = ...; instead of $.bisector1 = ...; Yes, that looks almost as nice as with the $, though perhaps a tad less. That leaves the issue of writing several methods that look like: method bisector1() is rw { return %:att }; Here is an attempt to do this using traits: # role hash_attributes { has %:att; multi sub trait_auxillary:(hash_attributes $trait, Class $container : [EMAIL PROTECTED] ){ $container does hash_attributes; for @atts -> $att { &($container)::($att) := method () is rw { return %:att{$att} }; } } } class Geometry::Triangle has hash_attributes <== { method calculate_sides(){ .side1 = ...; } } #= Does that look about right? I'd just use a hash attribute. All other things being equal, go for simple and standard. Does it look about standard? (especially the bit using the pipe operator)... Thanks, abhijit
Re: Classes with several, mostly unused, attributes
David Storrs wrote: On Dec 15, 2004, at 5:36 PM, Abhijit Mahabal wrote: I think that "slackness-on-demand" is a better policy than "strictness-on-demand", but that, again, is just my opinion Until now, the policy in Perl has always been that it is as slack and forgiving as possible, and you have to ask if you want it to be strict with you. I hope that doesn't change. --Dks There should be little reason to complain so long as it is drop-dead easy to turn on slackness. S01 says: # Perl 5 code is not strict by default, while Perl 6 code is. But it should be easy to relax with -e or maybe even a bare version number: perl -e '$x = 1' #!/usr/bin/perl -e $x = 1; #!/usr/bin/perl v6; $x = 1; Of course, you can counter that with "there should be little reason to complain so long as it is drop-dead easy to turn *strictness* on". But in either case, people are going to trip over this, expecting one(strictness/slacknesss) but getting the other. In one case (expecting slackness, but getting strictness from the compiler) it would be easier for the compiler to know that they have in fact tripped. --abhijit
Re: Classes with several, mostly unused, attributes
David Storrs wrote: Incidentally, I just want to go on record as saying that the verbosity of class declarations in P6 is really starting to skeeve me. I keep reminding myself that these are the edge cases that are being discussed, that you don't need all this stuff for the common case (right?) that Perl 6 can be pretty much the same easy, succint, fun language that I know and love, that sensible defaults will be chosen so that in the common case the things I get automatically are the things I wanted anyway. But, occasionally, I still find myself going "eeew...Java." I have been having the opposite feeling: I rather like the verboseness of class declarations, and their self documenting nature. It's not like java in that I have the freedom to be as specific or as vague as I want to be. I can say C<< has Cat %.foo is shape(Dog) >> if I want to, or C otherwise. Except for cases like the hypothetical Geometry::Triangle I can live with this, and maybe even in that case, because again it is probably a Good Idea. I don't know what happens when we have classes for which we do not know all the attributes ahead of time, but for that something like AUTOMETH would work. All this is subjective, of course, and I am fully with you that the possibility of being succinct should be open, to the extent that it is, er, possible. But there is a Pandora's box here: 1. When a class is composed, all the roles and the current class are meshed together; Clearly, if a role uses an attribute expecting it to be a particular type, it must explicitly say so (to avoid clashes with other roles or the class). Taciturnity, then, is open only to classes. 2. It will also be impossible to spot typos in argumentless method calls because that could be an undeclared attribute. (of the current class or any of its ancestors or roles) 3. If we use $.foo without declaring it, how would the compiler know if it is an object attribute or a class attribute? I think that "slackness-on-demand" is a better policy than "strictness-on-demand", but that, again, is just my opinion --abhijit
Re: Undeclared attributes
Dave Whipp wrote: Attributes are declared with C, but also have a unique signil C<$.>. So is it strictly necessary to declare them? Or rather, is it Cly necessary -- i.e. is the following legal? no strict; class Foo { method bar { say $.a++ } } For the standard layout, I'd think it'd be good to declare the attributes, but perhaps not necessary. An object of class C, IIRC, will just be an object in the parrot sense; doing an C will cause the attribute to be added to all other objects of that class, and to all objects that "is" or "does" that class; That might involve a whole lot of work. But maybe you are asking if Perl6 can intuit that you implied an unwritten C But it could be a C or C or C. BTW, should we be able to write pragmas like this: class Foo isnt strict{...} or class Foo isn't strict{...} --abhijit
Classes with several, mostly unused, attributes
Consider a class (e.g., the hypothetical Geometry::Triangle) that can have several attributes (side1, side2, side3, angle1, ang_bisector1, side_bisector, altitude1 and so forth), most of which will not be needed for most instances of Geometry::Triangle. I know how this can be done in P5. Using the layout "Hash" things are easy. How can P6 deal with this, without allocating too much memory to things that'd never get used? The layout "P6Hash" could come to the rescue, but there is still the issue of syntax: what exactly does C do? IIRC, in the P6Opaque layout, every instance of the class would have space the size of a PMC allocated for it. This behavior is not needed for P6Hash, and it should just leave attributes alone until they are assigned to (where defaults are also "assigns"). In which case, maybe for that layout we can get away without declaring all attributes, perhaps? (Since the declaration does nothing except help the parser). I was thinking whether we could do something like this: class Triangle is layout does autovivify{ method calculate_bisectors { $.bisector1 = ...; # $.bisector1 autovivifies } } where it is an error without the autovivify, and only P6Hash supports autovivification. --abhijit
Is object representation "per class" or "per object"?
According to S12, it is possible to supply the object layout to bless(), like so: $object = $class.bless(:CREATE[:repr] :k1($v1) :k2($v2)) But in the section "Introspection", "layout" is a class trait. Does this mean that classes have a default layout that can be overriden for individual objects? If the answer is "yes", what is the reason that somebody would want to have some objects of the same class as P6Opaque and others as PyDict? I can imagine needing to be able to *convert* from one layout to another, but then the converted object appears to me to belong to a different class (probably in a different language) and then layout should perhaps be an adverb for something like convert() or cast()*, instead of for bless(). Another reason for saying that the object laid out differently is a different class is that if for whatever reason you want some object either as P6Opaque or PyDict then you may also want both representations simultaneously, effectively requiring "two objects". What am I missing? A good example of the need of overriding the default class layout will suffice... --abhijit * maybe not even then, because we'd be saying $current_obj.cast($otherclass), and $otherclass would know it's own layout. Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: specifying the key Type for a Hash
On Mon, 6 Dec 2004, Larry Wall wrote: Hmm. Also says maybe you could attach a block to a hash or array to define what subscripting does. Hmm. That's tantalizing. Did you have something like this in mind: # Count number of accesses to each key our %counter_hash; my %hash is subscripted -> $subscript { %counter_hash{$subscript}++; %hash{$subscript} }; Or even: # Provide a "view" of the hash my %hash is subscripted -> $address { %hash{address_to_zipcode($address)}}; so that users can think that they are accessing %hash{"Bloomington, IN"} when they are really accessing %hash{47401}. Or scarier, using MMD-like stuff (I am not even thinking about syntax) we get different things based on the signature of the key, giving us the ability to differentiate between %hash{$Dog} or %hash{$Vet}. And pretty soon somebody will define an accessor for the signature (SQL_Query $s). It seems to me that this idea is not very far away from P5 "tying", but I may be wrong. If it is not very far away, maybe we can even have: my %hash is subscripted -> $s{ FETCH {...} STORE {...} } Crazy stuff. I don't know if it is doable or even desirable, but it sure is cool! Larry --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: specifying the key Type for a Hash
On Fri, 3 Dec 2004, Larry Wall wrote: : None of the synopses have anything like this. S6 talks about the : types of values, but not keys. Oversight, or is this syntax dead? S9 talk about it. Oops. Sorry. So it was oversight after all :) --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
specifying the key Type for a Hash
A6 included examples of syntax for specifying the type of the key for a hash: my %pet is Hash(keytype => Str, returns => Cat) None of the synopses have anything like this. S6 talks about the types of values, but not keys. Oversight, or is this syntax dead? --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Hyper Here-Docs?
On Wed, 1 Dec 2004, Damian Conway wrote: > Abhijit Mahabal wrote: > > > I am a little confused if the following is valid perl6: > > > > our &xsub = { $x }; > > No. Illegal attempt to assign to a reference. You want aliasing/binding > instead: > >our &xsub := { $x }; > > (I like to think of := as "assignment to symbol table entry".) Okay, that makes sense. A question about symbol tables, though: IIRC, only packages have symbol tables, and blocks don't: they just have a lexical pad. So is the C redundent? Is the following an error? my &xsub := { $x }; ? --abhijit Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Hyper Here-Docs? (was: Re: angle quotes for here-docs ?)
On Tue, 30 Nov 2004, David Christensen wrote: Incidentally, just like mathematically (albeit slightly loosely) an element of a set can be thought of as a function from any singleton, would it be possible for Perl 6 to provide a fast (under the syntactical point of view) way to promote a term to a function returning it? What's wrong with the perl 5: sub mysub($x) { return sub { $x }; # the sub{$x} is the construct } or the perl6 $xsub = { $x }; I am a little confused if the following is valid perl6: our &xsub = { $x }; I believe that would work and install this function in the package global symbol table because &xsub is the reference to the function xsub. If you wanted to get a function for each element in an array @a, I suppose you can say: sub makefunc($x){{$x}} @funcarray = @a>>.makefunc; And that can also be shortened to: @funcarray = @a>>{my $x=$^x;{$x}}; --abhijit
Re: But is it intuitive?
On Tue, 14 Sep 2004, Austin Hastings wrote: > I was thinking about removing files this morning, and realized that I > wish rm supported inclusion/exclusion. > > In particular, I wanted to remove "* but not Makefile" (since my > Makefile uses lwp-download to re-fetch the source code, etc.) > > It occurred to me to wonder: can P6's c do the same thing? > > That is, can I say: > > $my_rex = qr/fo*/ but not 'foo'; > > while (<>) { > unlink if /$my_rex/; > } The word "junction" came to my mind as I read your mail. $my_rex = qr/fo*/ & qr:not/foo/; (I don't think that :not is the option to negate, but there must be some syntax that works) I am not saying this is a better way to do it, but just another way that seems to do the same thing in the same way. > In general, what needs to be done to support this 'but, used as part of > a boolean'? --abhijit
Roles trying to be nice
Traits can be mean, but roles are "guarenteed"(=forced?) to play nice. But suppose I have a role that wants to play nicer, by ensuring that incorporating it in some class actually makes sense. For example, it may want to ensure that the class has $.foo. (*) I have a few questions: 1: Can this be achieved by a CHECK {} block in the role, that gets run just before the class composition is over? Or should it be spelled differently, CHECK {} being the last thing that run before "run-time"? 2: What is the syntax for checking that a class has a variable? In this case the class does not even really exist when we want to check. 3: If arbitrary things can go into such a CHECK{} block, then the following two may not mean the same: does A does B; does B does A; Are roles I to play nice, or I to play nice? --abhijit (*) The solution "add a C to the role itself, and if the class has a $.foo, it takes precedence" does not work because $.foo may have been added by another role. Abhijit Mahabal http://www.cs.indiana.edu/~amahabal/
Re: Progressively Overhauling Documentation
On Mon, 23 Aug 2004 [EMAIL PROTECTED] wrote: >>OK, there's one non-incremental idea: documentation that you can write >>in one place and display in some completely different order. (Shades of >>literate programming!) And although there are good reasons for keeping >>the docs in the same file as the code, there are equal but opposite >>reasons to keep it separate (if it's all piled up at the end of the file >>anyway). What gets presented to the user as "one page" could be bits >>and pieces from all over the place. > Literate Programming handles reordering by allowing you to specify a > hirearchical number as part of each doc piece. I am not sure I understand *why* you need reordering of documentation. Literate programming is useful because it reorders *code* while writing documentation in the intended order. Could somebody provide a concrete example of the need to reorder documentation? I was extensively using literate programming for the project I am working on. But after a while (7000 lines of p5 code, about 50 files) the cost of maintaining it seemed more than the gain even though I was heavily preprocessing the code to take the drudgery out, and I have come back to good ol' POD. I have come to believe that for short nasty pieces of code (implementing complicated algorithms) LP is a fantastic idea, but for larger systems that are not exactly "imperative" and have weird control flow (with hooks and such; or with an event loop of Tk), LP is no advantage. IMHO, for the few people who'd want to use LP, it would be easier and lazier to hack something like noweb to understand your annotations (perchance even understand POD :) ) than to make POD jump through hoops. --abhijit