On Thu, Jun 14, 2007 at 09:20:51AM -0600, Thom Boyer wrote: : Compare that with the simplicity that $larry & $damian are promoting.
Yes, and the simplicity we're promoting here is mostly *syntactic* simplicity. It's obvious that at a semantic level, there has to be a certain amount of incest between the two spheres (if indeed there are only two). From the Perl 6 perspective, information flows easily from the documentation to the program via the %=FOO pod twigil, because the Perl 6 parser is required to embed a pod parser specifically to guarantee that such values will be introspectable. Getting information to flow the other direction is more problematic because documentation is essentially passive data and must be interpreted by something external (often several different somethings). However, for a given language that uses pod for documentation, there can certainly be some conventions for making references to nearby declarations without having to repeat the entire declaration. Such references could be either by name or by position. Positional notation forces you to intersperse things you might not want to. What programmer really wants to see their function signature splattered out over many lines, or wants the beginning of the declaration off the screen before you get to the function body? Also, positional notation doesn't deal well with factoring out identical names from related entities that just want to share a chunk of documenation. So I think a named reference is a good compromise, where the name in the documentation (in some easily recognized syntactic form) refers to the next declaration (or set of declarations) of that same name. Hopefully the pod either knows implicitly or has been told explicitly how to parse out such declarations for insertion into the document. (And a positional notation could just be a degenerate case of not specifying the name (or using a name of * maybe), so it finds the next declaration of any name. Maybe even some kind of wildcarding works for hybrid situations.) The syntax for such named forward references is open for bikeshedding. (I've intentionally not given any examples in this message to avoid prejudicing the matter.) Larry
