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
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
> > 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
[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
[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 "#" 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
[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://") 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
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://") 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 "#" 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
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://") 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
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://") 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 "#" 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 Kalowsky"A 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
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 "#" 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
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.
> > to php.net/manual//.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://") 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 "#" 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
[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.
> to php.net/manual//.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 Kalowsky"A 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 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_docref() 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. to php.net/manual//.php marcus -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
