On Jun 8, 2007, at 11:44 AM, M. Sokolewicz wrote:
Hello all,
Since PHP 5 came out a lot of new extensions with classes and
predefined constants have appeared. As a result of all this, the
ref pages are getting huge. For instance, take the ref page for the
filter extension, it's one of the smaller ones, but even on this
one you've got a huge page with a large load of content which most
people just wanting a casual look at the extension couldn't care a
rats' ass about.
What I would like to see again is just that small list of functions
contained in that one extension and a separate page for all those
constants, another page for configuration directives, etc. Compare
it to eg. the Perl Regular Expressions section (not the look of the
ref section since that's bloated too IMO): it has separate pages
for Pattern Modifiers and Pattern Syntax.
Now, it might be just me, but I think we should think about what
the ref-page is actually for. Is it there (as I believe it should
be) to show a summary of what that extension IS and provide links
to other (sub)sections which explain it in detail if a user wished
to do so. Or is it there to dump all documentation that does not
fit anywhere else (like it seems to be used now) ?
Hoping this might spark a bit of a discussion :)
Nice, this is a good topic to think about and discuss because it's
true that the reference structure can get large and difficult to
read. Moving constants to their own page is semi-semi-official with
curl being a prime example:
URL: http://php.net/ref.curl
Commit: http://marc.info/?l=phpdoc&m=117300014115846&w=2
The "new" doc style only covers function pages and unfortunately did
not address reference.xml. Awhile back (~4 years) reference.xml was
split into sections like configure.xml, ini.xml, constants.xml, etc.
so that was a good start. As far as what should be viewable within
this page (php.net/ref.foo), I'm not sure but instead will also
brainstorm with a few ideas (and general statements) about the page
and section currently:
* Install: The installation procedure for Windows vs Linux is not
consistently structured. Sometimes just a couple different <para>'s
while other times separate sections/titles.
* Functions: Some extensions have 10, 100, 400 functions... how
useful is it to list all of these in ext.reference? 400 is a lot and
gets messy but at the same time it is the reference...
* Examples: Some sections have examples in the reference, should we
always have at least one here to show it off? Soon there will be a
push to have more examples everywhere too but the one in
reference.xml must really be top notch. examples.xml?
* PECL: This information is okay but needs improvement.
* Constants: Should no doubt be in their own page (see above).
* Changelog: How detailed should this be? Maybe aggregate changelogs
from every function too? Implementing this... anyone? :)
* FAQ: Should each section have its own FAQ? That would be nice. We
should consider being more faq/gotcha/tip friendly and not rely on
user comments for this but that's another topic.
* DEV HOWTO: Let's create a page that describes each element because
there are several sections/reftitles to use. This will be more
important after we come up with a new structure.
* Sections: For example ref.array has a lot of sort functions. We
could have a reference page (ref.array.sort or similar) that lists
and talks about them all. And Alex is working on a similar idea for
imagick mainly due to it having 400 methods... ;)
* Tutorial: Each section could have its own tutorial.
* Security: A security section related to the extension? Like it
might mention related php directives, file access, preferred external
lib versions, gotchas, etc.
And what the reference is for... let's see, it should explain what
the extension does, how to use, and reference everything related to
it. And people should not have to click a bunch of links to find
something about it... one maximum. Everything related to the
extension should be easily found. Having all information in one page
has its advantages but as Maciek said stuff like constants can
overwhelm the page. The Install and Configure sections... not sure
about those, perhaps one page together. One thing to keep in mind is
the current structure is a big reason why people love the PHP Manual
so much but still let's not be afraid to improve it. Also changes
require work both initially and for translators so changes are not to
be taken lightly.
The discussion here could end up creating a nice structure for every
reference.xml to follow so please everyone feel free to throw all
ideas on the table... even crazy ones.
Regards,
Philip
