Audrey has asked me to split S29 AKA Perl6/Spec/Functions.pod up due to its rapidly expanding size. The strategy that she suggested is basically what I'm leaning toward, but I wanted to get feedback (esp. from Larry and other Synopsians).
I want to be clear, I'm not asking for help coming up with a way to do this, just trying to see if I'm going to completely hose The Plan(tm). Something like this could easily be a week-long thread, and I don't want to go there unless I really have to. "S29: Functions" will be an overview, and will contain a sectional format as it does now, broken up by high-level modules. This isn't in question, since three of us who have worked on it have found this to be the best way to approach it, and it's not the best use of my time to go re-writing the whole structure, anyway. Each section will lead with a blurb about the module and a reference to its API document. For the most part, these sections will be populated with functions, but method variants where there is a functional equivalent will only get a passing mention and no signature. Method-only entries will not be mentioned in this document, and instead will be moved out to the API document specific to the module/class in question. Modules which are very self-contained (e.g. Math::Trig) will JUST get a blurb, suggesting that the reader peruse the appropriate API document. Modules which have relatively generic OS or other non-core language features may be abbreviated, and some functions may get little or no mention. These details will be moved out to the API document for the module in question. Constants will be entirely in the API document, but will probably get a short note in S29. A "Compatibility" section will be added which will break all of the Perl 5 functions from perlfunc down into several categories: * As-is - the old usage is essentially unchanged (e.g. sprintf) * Altered - The new usage is functionally different, but similar (or a subset, e.g. eval) * Name only - The new usage has almost nothing to do with the old (e.g. each) * Compatibility - The old name is supported, but deprecated (e.g. chr) * Unsupported - The old name is gone (e.g. waitpid) If a function is not exported by default, it will also be noted in this section. In this way, even though S29 may not contain every function available to Perl 6 programmers as a builtin, it will at least give Perl 5 programmers a sense of what happened to what they knew. The API documents should probably be the more authoritative reference for implementing P6 core libraries. -- Aaron Sherman <[EMAIL PROTECTED]> http://www.ajs.com/~ajs/ Mushroom Photography: http://mush.ajs.com/news/