ID: 28295
Updated by: [EMAIL PROTECTED]
Reported By: m at bytech dot fi
-Status: Open
+Status: Closed
Bug Type: Documentation problem
PHP Version: Irrelevant
New Comment:
This bug is old :) Anyway, I don't think functions should ever be
hidden. Highlighted, sure, but never hidden. Users should know they
exist and usually these functions have examples for the older versions
of PHP so viewing them is a benefit to all.
This bug is closed. LiveDocs already implements this and we've mostly
stopped adding features to DSSSL. All hail LiveDocs!
Previous Comments:
------------------------------------------------------------------------
[2004-05-09 15:46:50] [EMAIL PROTECTED]
may I suggest a small version of the "version 5 in a circle" graphic we
have on php.net right now.
This little graphic can live in the phpweb theme (but make a copy of it
for the default livedocs theme too) as it is likely that different sites
will want a different rendition of the version number. (remember to "cvs
add -kb" the graphic)
Also, thinking forward, I'd like to make this kind of generic by
highlighting functions of the latest major version. We can achieve
this by defining a LATEST_VERSION constant to have the value of 5;
whenever a function is introduced in the LATEST_VERSION, we can pull in
LATEST_VERSION . '.gif' as the graphic.
When we get closer to PHP 6, all we'd need to do then is add a version
6 graphic and increment LATEST_VERSION.
------------------------------------------------------------------------
[2004-05-09 15:30:54] [EMAIL PROTECTED]
The code for <function> and the TOC in ref.pages is exactly the same,
because the TOC returns:
<function>xpto_func</function> - $title
And then this is parsed by the format_function() function.
This won't be hard to implement. If we agree in the presentation style,
I may implement this.
------------------------------------------------------------------------
[2004-05-09 15:07:40] [EMAIL PROTECTED]
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?
------------------------------------------------------------------------
[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).
------------------------------------------------------------------------
The remainder of the comments for this report are too long. To view
the rest of the comments, please view the bug report online at
http://bugs.php.net/28295
--
Edit this bug report at http://bugs.php.net/?id=28295&edit=1
