S29 demerge and API document plan
Aaron Sherman
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 <a...@ajs.com>
http://www.ajs.com/~ajs/
Mushroom Photography: http://mush.ajs.com/news/