ID: 28295 Updated by: [EMAIL PROTECTED] Reported By: m at bytech dot fi Status: Open Bug Type: Documentation problem PHP Version: Irrelevant New Comment:
Good idea :) It would be nice, if we could modify our presentation code (DSSSL and livedocs) to put a little [5] sign or something like that after all the function names that are supported in PHP 5 only. I mean if we have a <function>php5_magic_function</functoin> then the output would be php5_magic_function()[5] (with the [5] being some good looking image or a <sup>-ed text). This would not hide the functions but mark them in the manual occurances. Also it would be nice to do the same on the reference TOC pages (which is different rendering code). Anyone with interest to code this? Previous Comments: ------------------------------------------------------------------------ [2004-05-06 11:01:32] m at bytech dot fi Well, hiding (or highlighting) PHP5 only functions alone would be a significant improvement. The functional differences between versions are less important to separate, because whether the functionality is the same or not the user is already reading the documentation for the function at that point. And of course, the function is available at least in some form regardless of the version. On the other hand, it's only annoying that the documentation for strpos() lists functions stripos() and strripos() in the "See also" part, since they are not available in any form in versions prior to PHP5. ------------------------------------------------------------------------ [2004-05-06 10:46:33] [EMAIL PROTECTED] Consider yourself privileged ;-) DocBook is a beast, and we have 30 or so different languages to maintain! It would be fairly simple to hide functions that are PHP 5 only, but in many cases we have features that differ by PHP version; these would be impossible to parse automatically without some kind of AI that understands English (and one for each of the other languages). ------------------------------------------------------------------------ [2004-05-06 10:33:34] m at bytech dot fi I imagine this could initially be done so that the version information that already exists in the current documentation would be automatically parsed, and then the remaining version information could be applied later. And the version checking could also be done by a community effort. I'm not familiar with the documentation system that the php.net docs use, but the version data that is already available there is pretty extensive (especially with PHP5 specific functions), and generally speaking in a format that could easily be automatically parsed from the documentation. And of course, good things often require some effort. :) ------------------------------------------------------------------------ [2004-05-06 10:24:20] [EMAIL PROTECTED] Would be good, but also a lot of effort for the doc team to audit the whole text. I'm not even sure if DocBook has a way to version sections of text. ------------------------------------------------------------------------ [2004-05-06 09:55:16] m at bytech dot fi Description: ------------ It would be very helpful if it was possible to better distinguish PHP5 specific functions when browsing the documentation. A lot of people will be coding for PHP4 for quite some time, and showing functions that are only available in PHP5 or in CVS might be confusing to them. Of course the version compatibility of the function is displayed on the top of every help page, but this is very easy to miss. And considering the sheer amount of functions that are available, some kind of limiting would be quite beneficial. This separation could be done in several ways, for example: - Separate documentations in different locations - Through a "My php.net" setting - Displaying new functions in different color - Hiding new functions completely This setting could naturally also be used to otherwise customize the help system, for example hiding functions for extensions that are rarely used, or setting the preferred PHP version number and showing only the functions that are relevant to that version, etc. ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/?id=28295&edit=1
