[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] php_error_docref
At 10:15 14.08.2002, Jan Lehnardt wrote: Hi, On Wed, Aug 14, 2002 at 10:09:52AM +0200, Marcus Börger wrote: Then there is only the last argument not spoken about yet: Externally developed extensions. and PECL extensions respectively. For external developed extensions I suggest putting them into PECL (at least the documentation, if there are license issues about the extension's code itself) and for PECL docs I suggest some kind of shortcut like: php.net/pecl.function and php.net/pear.function while we are at it. Erm - good point we cannot find pecl.function.name automatically by docref=NULL. Either pecl must be available by function.name or by just using name on php.net. This is also a problem for external copies of the manual. marcus -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV]php_error_docref
Then there is only the last argument not spoken about yet: Externally developed extensions. and PECL extensions respectively. For external developed extensions I suggest putting them into PECL (at least the documentation, if there are license issues about the extension's code itself) and for PECL docs I suggest some kind of shortcut like: php.net/pecl.function and php.net/pear.function while we are at it. | Erm - good point we cannot find pecl.function.name automatically by | docref=NULL. Either pecl must be available by function.name or by | just using name on php.net. This is also a problem for external copies | of the manual. PECL, PEAR and other functions won't be available as function.name or even name from php.net because namespace issues. We have enough URL shortcuts now ( see http://php.net/urlhowto ). Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] php_error_docref
At 10:57 14.08.2002, Gabor Hojtsy wrote: Then there is only the last argument not spoken about yet: Externally developed extensions. and PECL extensions respectively. For external developed extensions I suggest putting them into PECL (at least the documentation, if there are license issues about the extension's code itself) and for PECL docs I suggest some kind of shortcut like: php.net/pecl.function and php.net/pear.function while we are at it. | Erm - good point we cannot find pecl.function.name automatically by | docref=NULL. Either pecl must be available by function.name or by | just using name on php.net. This is also a problem for external copies | of the manual. PECL, PEAR and other functions won't be available as function.name or even name from php.net because namespace issues. We have enough URL shortcuts now ( see http://php.net/urlhowto ). Goba I was just about explaining in detail but now i am more likely to look for a better solution - posting here if i can find any. Until i find one pecl and pear extensions will not be able to set docref=NULL. marcus -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV]php_error_docref
| Erm - good point we cannot find pecl.function.name automatically by | docref=NULL. Either pecl must be available by function.name or by | just using name on php.net. This is also a problem for external copies | of the manual. PECL, PEAR and other functions won't be available as function.name or even name from php.net because namespace issues. We have enough URL shortcuts now ( see http://php.net/urlhowto ). I was just about explaining in detail but now i am more likely to look for a better solution - posting here if i can find any. Until i find one pecl and pear extensions will not be able to set docref=NULL. If you know that an error is issued from a PECL or a PEAR extension, than it's equally easy to have a URL for php.net/pear.func or pear.php.net/func Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
At 16:37 13.08.2002, Dan Kalowsky wrote: A few comments on this. 1) is it possible to cut down on the number of php_error_docref functions to just one? I really don't see a reason for this many different formats. There is no solution for reducing php_error_docrefn() to one function call but we could exchange all php_error() calls to php_error_docref(). Again see automatic exchange script: http://marcus-boerger.de/php/ext/docref.txt But who will do this? Me not. 2) Can we please remove the http://www.php.net/manual/en/blahblahblah; style of use for this? It will tend to force users into one language or another, and not make PHP as friendly/usable to other languages. NO! First you can simply set docref_root in your ini to point to your local copy of the manual in whatever language and Second it is a problem of the php website. It should automatically redirect from php.net/function.functionname to php.net/manual/yourlanguage/functionname.php marcus -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
On Tue, 13 Aug 2002, Marcus [iso-8859-1] Börger wrote: 2) Can we please remove the http://www.php.net/manual/en/blahblahblah; style of use for this? It will tend to force users into one language or another, and not make PHP as friendly/usable to other languages. NO! First you can simply set docref_root in your ini to point to your local copy of the manual in whatever language and Second it is a problem of the php website. It should automatically redirect from php.net/function.functionname to php.net/manual/yourlanguage/functionname.php I'm not sure I see the point still. What I'm proposing is not allowing: php_error_docref(http://www.php.net/manual/en/function.fopen; TSRMLS_CC, E_WARNING, Spongebob Square Pants rules); as a valid call from within an extension. Because this limits anytime this error occurs to the English manual description only, or any language which is defined really. There is no need for this, as you have provided another option which works much cleaner and better (through the ini options) in my opinion. While the PHP website may have a bug (or two) in it, it's no reason to force end users to be reading languages that they don't know or prefer. I have nothing wrong with: php_error_docref(function.fopen TSRMLS_CC, E_WARNING, Spongebob Square Pants lives in a pineapple under the sea); To me that should be the recommended method, as it will allow the php.ini values for language to override everything nicely, and everyone can see the PHP manual in their desired language. The error of course is still in English but thats another matter. --- Dan KalowskyA little less conversation, http://www.deadmime.org/~danka little more action. [EMAIL PROTECTED]- A Little Less Conversation, [EMAIL PROTECTED]Elvis Presley -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
At 17:05 13.08.2002, Dan Kalowsky wrote: On Tue, 13 Aug 2002, Marcus [iso-8859-1] Börger wrote: 2) Can we please remove the http://www.php.net/manual/en/blahblahblah; style of use for this? It will tend to force users into one language or another, and not make PHP as friendly/usable to other languages. NO! First you can simply set docref_root in your ini to point to your local copy of the manual in whatever language and Second it is a problem of the php website. It should automatically redirect from php.net/function.functionname to php.net/manual/yourlanguage/functionname.php I'm not sure I see the point still. What I'm proposing is not allowing: php_error_docref(http://www.php.net/manual/en/function.fopen; TSRMLS_CC, E_WARNING, Spongebob Square Pants rules); The point is to be able to direct to external sites not on php.net! For example when a function is just a wrapper around a library then you can use the absolute form of the docref parameter (http://site) to point to the library's website. as a valid call from within an extension. Because this limits anytime this error occurs to the English manual description only, or any language which is defined really. There is no need for this, as you have provided another option which works much cleaner and better (through the ini options) in my opinion. While the PHP website may have a bug (or two) in it, it's no reason to force end users to be reading languages that they don't know or prefer. I have nothing wrong with: php_error_docref(function.fopen TSRMLS_CC, E_WARNING, Spongebob Square Pants lives in a pineapple under the sea); To me that should be the recommended method, as it will allow the php.ini values for language to override everything nicely, and everyone can see the PHP manual in their desired language. The error of course is still in English but thats another matter. NULL or #target is best here since it allows the phpdoc group to change their mind for naming the pages. regards marcus -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] Re: [PHP-DEV] php_error_docref
php_error_docref(function.fopen TSRMLS_CC, E_WARNING, Spongebob Square Pants lives in a pineapple under the sea); To me that should be the recommended method, as it will allow the php.ini values for language to override everything nicely, and everyone can see the PHP manual in their desired language. The error of course is still in English but thats another matter. | NULL or #target is best here since it allows the phpdoc group to | change their mind for naming the pages. It's not likely that this naming scheme will change. Internal linking, php.net/funcname lookups, IDE integrations all depend on this naming scheme... Goba -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
On Tue, 13 Aug 2002, Marcus [iso-8859-1] Börger wrote: The point is to be able to direct to external sites not on php.net! For example when a function is just a wrapper around a library then you can use the absolute form of the docref parameter (http://site) to point to the library's website. Okay thats a point I hadn't thought of. Though I'm not sure why we'd be referencing outside sites. Can we then change the CODING_STANDARD example to NOT use the php.net website? Hopefully stopping anyone from using it as a reference to any php-specific documentation, and only for external sites. NULL or #target is best here since it allows the phpdoc group to change their mind for naming the pages. Then again, I don't understand what this parameter is for. If not for the developer to declare which help file this is in, what is the point? Yes I see the anchor tags option, but what is the difference between using an anchor and declaring specifically? It just seems that if this variable is going to be 90% of the time (random guess) NULL, it's not really all the necessary to be included. And judging from the comment by Gabor, the PHPDOC group isn't going to change this format anytime soon. --- Dan KalowskyA little less conversation, http://www.deadmime.org/~danka little more action. [EMAIL PROTECTED]- A Little Less Conversation, [EMAIL PROTECTED]Elvis Presley -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
On Tue, 13 Aug 2002, Dan Kalowsky wrote: On Tue, 13 Aug 2002, Marcus [iso-8859-1] Börger wrote: The point is to be able to direct to external sites not on php.net! For example when a function is just a wrapper around a library then you can use the absolute form of the docref parameter (http://site) to point to the library's website. Okay thats a point I hadn't thought of. Though I'm not sure why we'd be referencing outside sites. Can we then change the CODING_STANDARD example to NOT use the php.net website? Hopefully stopping anyone from using it as a reference to any php-specific documentation, and only for external sites. Do you think this will help the lost PHP script writer? For example, the cURL extension is really just a wrapper around libcurl. If they get an error on curl_setopt() do you really want to direct them to the C API docs on the cURL site? I think it should always point to the php.net manual; external sites won't help the PHP script writer with their PHP code. From the PHP manual they can go to library website if need be. My $.02. --Ricky -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
At 22:04 13.08.2002, Dan Kalowsky wrote: On Tue, 13 Aug 2002, Marcus [iso-8859-1] Börger wrote: The point is to be able to direct to external sites not on php.net! For example when a function is just a wrapper around a library then you can use the absolute form of the docref parameter (http://site) to point to the library's website. Okay thats a point I hadn't thought of. Though I'm not sure why we'd be referencing outside sites. Can we then change the CODING_STANDARD example to NOT use the php.net website? Hopefully stopping anyone from using it as a reference to any php-specific documentation, and only for external sites. NULL or #target is best here since it allows the phpdoc group to change their mind for naming the pages. Then again, I don't understand what this parameter is for. If not for the developer to declare which help file this is in, what is the point? Yes I see the anchor tags option, but what is the difference between using an anchor and declaring specifically? It is there for directing to one specific page. For example i am going to write the common errors for exif only on the exif_read_data page. So i must set docref parameter of all calls to php_error_docref() within exif to exif-read-data#error. Another problem is that you can direct to configuration pages and so on if the error coccured due to a missconfiguration. It just seems that if this variable is going to be 90% of the time (random guess) NULL, it's not really all the necessary to be included. It was intended to be the right parameter for abot 95%. And judging from the comment by Gabor, the PHPDOC group isn't going to change this format anytime soon. I hoped so :-) marcus -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
At 22:22 13.08.2002, 'Ricky' S Dhatt wrote: On Tue, 13 Aug 2002, Dan Kalowsky wrote: On Tue, 13 Aug 2002, Marcus [iso-8859-1] Börger wrote: The point is to be able to direct to external sites not on php.net! For example when a function is just a wrapper around a library then you can use the absolute form of the docref parameter (http://site) to point to the library's website. Okay thats a point I hadn't thought of. Though I'm not sure why we'd be referencing outside sites. Can we then change the CODING_STANDARD example to NOT use the php.net website? Hopefully stopping anyone from using it as a reference to any php-specific documentation, and only for external sites. Do you think this will help the lost PHP script writer? For example, the cURL extension is really just a wrapper around libcurl. If they get an error on curl_setopt() do you really want to direct them to the C API docs on the cURL site? I think it should always point to the php.net manual; external sites won't help the PHP script writer with their PHP code. From the PHP manual they can go to library website if need be. I thought of situations where an external document explains a standard that must be used. For example when a database extension can deliver any url describing the query error you can use php_error_docref() to point to that page. It is no solution for cURL where only C library or a standard exists as external URLs. regards marcus -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-DEV] php_error_docref
It's needed because a lot of the doc pages are long, and there is not always going to be a 1:1 mapping between the active function and a description of the error. For example, in the stream wrappers, when someone tries to open an http connection for write, or tries to overwrite an existing file via ftp, we will want to inform the user that we don't support this action. Now, if fopen was the only function that createdwrappers, we could use a NULL for the docref. In actual fact fopen(), copy(), and other extensions will all be using wrappers, so the active function becomes meaningless. Couple that with the main description of using URLs not actually being on the fopen manual page (it's under features.remote-files), and because that page is really long, finding the two lines that say you can't do that is pretty hard work. So, we do need the '#target' syntax in there :-) --Wez. On 08/13/02, Dan Kalowsky [EMAIL PROTECTED] wrote: NULL or #target is best here since it allows the phpdoc group to change their mind for naming the pages. Then again, I don't understand what this parameter is for. If not for the developer to declare which help file this is in, what is the point? Yes I see the anchor tags option, but what is the difference between using an anchor and declaring specifically? It just seems that if this variable is going to be 90% of the time (random guess) NULL, it's not really all the necessary to be included. -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
