On Thu, Apr 10, 2008 at 12:11:05PM -0700, jerry gay wrote: : On Thu, Apr 10, 2008 at 11:23 AM, Larry Wall <[EMAIL PROTECTED]> wrote: : > On a larger question, I'm wondering if it's time to slush/freeze : > the Synopses as historical documents and put all spec effort into : > the new form (presumably as a wiki that knows how to serialize into : > a document). I don't think we have the bandwidth to maintain multiple : > standard documents. Well, okay, *I* don't have the bandwidth... : > : from the perspective of a language implementor, i believe that : formalization may be a benefit in the long term. however, it will : cause some short-term disruption with which i'd greatly appreciate : help.
Not to panic; there is almost certainly a creative path through this. : specifically, the spec test suite employs the use of smartlinks, which : are pod-like tags used to relate a set of tests to specific locations : in the synopses. modification of the spec format will require : modification of the spec test suite, and the coverage/reporting tools : (e.g. smartlinks.pl.) Nothing needs to change there over the short term. We aren't deleting the Synopses. :) : also, modification of the spec file type from : .pod to .odf will certainly add to the complexity of any tool : migration. as multiple implementations of the spec are now maturing, : these tools have become more important to judging the progress of any : implementation. If the spec file type ends up .odf at some point, it will be an accident. I think of it more as wikified pod. Smartlinks are fine, but we're running into the limitations of naming pieces of spec, which really has little to do with what format they're in, and *shouldn't* have much to do with the organization of the specs. You're looking for an invariant, and that's fine, but the *orderedness* of the various bits of the Synopses cannot be that invariant over the long term. In short, we need invariant symbolic indexing, not invariant numeric indexing. : also, as manager for the parrot and perl 6 projects under the perl : foundation umbrella for google summer of code (GSoC), i'd like to note : that there's a chance we'll have a student working on a project to : improve the perl 6 test suite. i expect this student to make good use : of today's existing tools, like smartlinks.pl, in the course of his : project. reformatting the spec documents will likely implement this : effort, and may lead to a failed project where the student will not be : compensated. i certainly don't want to see that happen. i'll know more : about whether or not this project has been accepted in the coming : week. It may well be that the smartlinks can be made a hair smarter, and point to an abstract naming scheme rather than a concrete file. Think URLs, not trying to navigate a .odt file. : i hope that the hackathons during the upcoming conference season will : be a place where folks can help us improve the spec test suite, and : that a spec document format change today will be disruptive. i'd love : to see folks helping out with migration to a new documentation format, : as well, but i think it's easier if we keep the current documents : up-to-date until the migration is considered complete. Which is why I said slush/freeze rather than freeze. In any case, not all smartlinks have to be converted at once. And the naming scheme that rides above the document organization may well continue to resemble synopses numbers and section content. As usual, we're just thinking about another level of indirection... :) : i believe that if we put effort into migrating to a new format, while : keeping the current spec pod format as canon, and later (post-GSoC) : marking the current spec documents as historical, it will allow time : for implementation, documentation, and testing projects to move : forward during the traditionally busy summer months. It will always be too early, and too late. There will always be reasons not to do it till next year, and reasons you're hosed because it wasn't done years ago. Now is all we've got at the moment... Larry
