Philip Olson wrote:
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
Speaking of constants specifically, I've just had a look at the
http-extension page and I must say I like the way they are ordered. Each
constant belongs to a block which actually tells you what it is for; ie.
"
Constants usable with http_parse_cookie() and its return value
HTTP_COOKIE_PARSE_RAW (integer)
don't urldecode values
HTTP_COOKIE_SECURE (integer)
whether "secure" was found in the cookie's parameters list
HTTP_COOKIE_HTTPONLY (integer)
whether "httpOnly" was found in the cookie's parameter list
"
The constant (hah!) repeating of the word "Constants this" and
"Constants that" drives you nuts after a while, but at least it's
structured in a way that would be useful to a user. The lists as they
seem to exist in most other extension-pages don't seem to be structured
(nor usually documented) at all, aside from being sorted alphabetically
(and even that, not always).
About Installation, as far as I can tell, can't we simply state "can be
installed like all pecl extensions, see here for more info: [link to
Pecl install page]". Currently each extension has the section
" This » PECL extension is not bundled with PHP. Information for
installing this PECL extension may be found in the manual chapter titled
Installation of PECL extensions. Additional information such as new
releases, downloads, source files, maintainer information, and a
CHANGELOG, can be located here: » http://pecl.php.net/package/crack.
In PHP 4 this PECL extensions source can be found in the ext/ directory
within the PHP source or at the PECL link above. In order to use these
functions you must compile PHP with Crack support by using the
--with-crack[=DIR] configuration option.
Windows users will enable php_crack.dll inside of php.ini in order to
use these functions. In PHP 4 this DLL resides in the extensions/
directory within the PHP Windows binaries download. The DLL for this
PECL extension may be downloaded from either the » PHP Downloads page or
from » http://pecl4win.php.net/ "
which does not differ from extension to extension (apart from the name),
any extra installation info is obviously good to have, but there's so
much stuff being repeated (!) (yes, I am a minimalist when it comes to
such things).
I have a few other things I noticed about the pages that I think could
be done differently, but that'll have to wait, as I'm not even sure if
my ideas for it are doable.
- Tul
