php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #24861 Categorize function references
Submitted: 2003-07-29 17:50 UTC Modified: 2007-12-28 01:16 UTC
Votes:2
Avg. Score:3.0 ± 2.0
Reproduced:2 of 2 (100.0%)
Same Version:2 (100.0%)
Same OS:2 (100.0%)
From: tim at zer0-interactive dot com Assigned: goba (profile)
Status: Closed Package: Documentation problem
PHP Version: Irrelevant OS: N/A
Private report: No CVE-ID: None
 [2003-07-29 17:50 UTC] tim at zer0-interactive dot com
Description:
------------
This isn't so much a problem with any piece of documentation in particular, but rather the usability of the documentation as a whole.

Having watched PHP grow over the last few years and trying to keep on top of the numerous extensions that keep appearing over time, it is getting increasingly hard to detirmine what each extension is for without going further into the documentation to read about it.  I would say that is more of a problem with non *nix developers who may not have heard of what some of the extensions are and what they are for.

In light of this, I think that it would be beneficial, particularly for the newbie developer, if the online documentation where organised slightly differently.  Namely in the area of categorising the function reference section into high level chunks.

Take for example the following question: what different databases does php support?  This is not an easy question to answer unless you know what all the extensions do first when you are reading through the index.

If it were reorganised slightly so it was something like this:

Database Functions
   . MySQL Server Functions
   . MS SQL Server Functions
   . ODBC Functions
Filesystem Functions
   . Directory Functions
   . File Functions

An addition to this format would be the ability to collapse these sections on the page so that you do not have this massive list staring back at you.

The documentation provided so far has been great, but I think the format of the index is holding it back from growing much further while still making it easy to locate what you are looking for.  This index format would bring it into consistency with indexes such as how the PEAR packages are listing.  A high level category with the actual packages listing inside those categories.

I believe this indexing solution to accomdate not only for future growth of the documentation, but also makes it easier to use while still maintaining the integrity of the current documentation.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2003-07-30 05:03 UTC] goba@php.net
I can assure you that such a categorization will be in place, hopefully in the near future. We are working on a better manual presentation system for our website (and all mirror sites), which will include categorized listing of extensions too. This is planned for a long time, but we need more time to complete the background programs.

Assigning to myself, I will close this bug, when the solution is in place (despite that I will not implement the solution ;).
 [2004-08-08 19:57 UTC] goba@php.net
The suggested and soon to be implemented grouping is here:

  http://cvs.php.net/co.php/phpdoc/RFC/manual.xml.in

Livedocs needs to be able to handle this type of TOC on the index page (and elsewhere). We are not going to implement support for this in the DSSSL or XSLT sheets IMHO.
 [2004-08-09 13:05 UTC] verdy_p at wanadoo dot fr
This bug is quite old and I reported it 2 years ago:
http://bugs.php.net/bug.php?id=17164
Nothing was done about it, and bug 17164 was forgotten.
Now bug 17164 is closed (it was not bogous as stated now, but is now a duplicate with this newer bug report).
before this bug was incorrectly reopened here.

The solution proposed here with the xml.in file seems good and replies correctly to bug report 17164...
 [2004-08-09 14:06 UTC] goba@php.net
verdy_p, you also submitted a duplicate. What bug do we choose from multiple issues dealing with the same problem is upon is. It is not the earliest timestamp we choose, but it is the most relevant bug report. The xml.in file itself does not solve the problem, since there are no tools currently supporting the building of the docs with that structure.

This bug is not forgotten, just noone had the time yet to take care of it. If you are willing to help, you could equally offer your time as others do in this project.
 [2005-07-25 08:57 UTC] vrana@php.net
This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.

http://cvs.php.net/co.php/phpdoc/en/appendices/extensions.xml

In future, it can be swapped (alpabetical list in appendix, categories in the contents).
 [2007-12-28 01:16 UTC] bjori@php.net
(See also http://docs.php.net/funcref)
 
PHP Copyright © 2001-2019 The PHP Group
All rights reserved.
Last updated: Tue Apr 23 00:01:25 2019 UTC