php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #73698 It's hard to find standard PHP library functions in Function Reference
Submitted: 2016-12-09 07:56 UTC Modified: 2018-06-24 16:31 UTC
From: sobak@php.net Assigned:
Status: Open Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
 [2016-12-09 07:56 UTC] sobak@php.net
Description:
------------
Hi,

I started a non-biding discussion on /r/php regarding ways we could improve PHP Manual experience. One of complaints (which I also heard before) is that it's hard to find PHP standard library functions.

https://www.reddit.com/r/PHP/comments/5h7c5w/how_can_be_the_php_manual_improved/daz2jj8/

I think that I know the reasoning behind that. Moreover, I think is valid. There is hard to define what exactly "PHP Standard Library" is (I'm talking about SPL). One version of PHP can have `php-src/ext/calendar/` bundled and other can not. Extensions can also be excluded when compiling etc, etc.

But let's focus on `php-src/ext/standard` for now. Those are basic functions which are always available, but finding them in the manual using TOC's is rather difficult.

Let's take `file_exists()` as an example - pretty basic function.

php.net/manual/en/ (or even PHP.net -> Documentation -> English) -> Function Reference -> File System Related Extensions -> Filesystem -> Filesystem Functions -> file_exists()

Not only it's very long way to get there, I think that most of these people is lost on "File System Related Extensions". I doubt they treat `file_extists()` as any kind of an extension (once again, I do understand, why we treat it as such in terms of manual structure).

So, what I would propose is either:

1) Restructure phpdoc/reference/ to contain /standard/ directory, then divided into /strings/, /array/, /filesystem/ etc. (what exactly should be included there is another part of discussion, I think).

That sounds good, but I'm not even sure whether our current build system would allow that. It's all about xml:id's and their hierarchy, what defines our TOC's, right?

2) Don't change the hierarchy and structure at all but somehow hardcode URL's to them on top of "Function Reference". Something like:

Function Reference
- Standard library
-- Arrays
-- Filesystem
-- Strings
- Affecting PHP's Behaviour
- Audio Formats Manipulation
- Authentication Services
[...]

I'm willing to take care of implementing that, but I'd like to know opinions of more experienced Doc Team's members.


Patches

Pull Requests

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2018-06-24 16:31 UTC] cmb@php.net
> It's all about xml:id's and their hierarchy, what defines our
> TOC's, right?

Well, the structure is defined by manual.xml.in[1], and could be
changed (or perhaps augmented).

[1] <http://svn.php.net/viewvc/phpdoc/doc-base/trunk/manual.xml.in?view=markup>
 
PHP Copyright © 2001-2024 The PHP Group
All rights reserved.
Last updated: Thu Oct 10 14:01:27 2024 UTC