Re: [PHP-DOC] Patch backlog on en

[Peter Cowburn]

Hi Chris,

On 31 August 2013 00:56, Chris Wright  wrote:

> Hi list
>
> Over the last few days I've been pushing to clear out the backlog of
> patches
> for review under en and I'm down to 3 remaining:
>
> - #911 is pgsql related, a subject on which I'm not particularly well
> versed.
>   I'd appreciate it if someone knowledgeable on the subject could review
>   it and take the appropriate action.
>

Unfortunately, I don't have the availability to review the patch at the
moment. From a very quick glance (literally, just that) there are a few
markup issues like wrapping  around multiple words, and the use
of "you" (which we frown upon).


>
> The other two were created by users with VCS access as as such I am
> unable to clear them, if someone with admin karma/generally the ability
> to do so could handle them I would appreciate it:
>
> - #927 - I have spoken to the original author and have been informed that
>   the patch is invalid. It just needs reverting.
>

I've deleted this patch.


>
> - #896 - I am still researching the validity of this patch. If anyone can
> give
>   it an instant yay/nay that would be good, also Is there anything that can
>   be done to unlock it so that when I have reached a conclusion I am able
>   to handle it?
>

I have set you as the file owner so you should be able to make any further
changes that you want.


>
> I would like to get the backlog cleared out asap, in an effort to make the
> "contributions are ready for review" automated emails to the list a bit
> more
> useful (i.e. they only get sent out when there's a new patch, rather than
> the patches that have been hanging around for months).
>
> Thanks for any assistance you can offer on this
>

Thank you!


>
> ---
>
> Chris Wright (DaveRandom)
>

Re: [PHP-DOC] Hello world - another person who wants to get involved

[Peter Cowburn]

On 19 August 2013 09:36, Chris Wright  wrote:

> Hi Guys/Gals
>

Hi Chris!


> I would like to get more involved with the docs team.
>

Good to hear.


> I have already created a couple of patches:
>
> https://svn.php.net/viewvc?view=revision&revision=331156
> https://edit.php.net/?patchID=952&project=PHP


Thanks for your contributions thus far.


> and I would appreciate any feedback you might have on these. I
> would also like to
> get more involved in moderating other patches - I see several
> outstanding patches that
> look like a decisive action could be taken that have been waiting for
> some time, a
> month or more,


That is something we haven't been very good at. Anyone willing to do a
little bit of leg-work on that front would be welcome.


> and I would also like to get involved by helping to document new
> features and changes as they are added to PHP.


>
> - Chris Wright (DaveRandom)
>

I'd encourage you to keep doing work in the online editor, saving patches,
etc.  Also, fill out the PHP Account Request Form (ignore all of the Git
references, for now) at http://www.php.net/git-php.php as I'd be more than
happy to see you join us.

I think I've already given you the links to our "documentation how-to"
pages. Study them. If you're brave enough, get a local checkout of the
documentation so you can make, and importantly validate, changes locally.

Cheers,

Peter

Re: [PHP-DOC] PHD renders and as tags in HTML; this is problematic.

[Peter Cowburn]

On 30 June 2013 17:32, Levi Morrison  wrote:

> On Wed, Jun 26, 2013 at 3:17 PM, Peter Cowburn wrote:
>
>> On 26 June 2013 21:10, Levi Morrison  wrote:
>>
>>> I currently don't know anything about PHD. I'm willing to learn and work
>>> on this, but my understanding is that before I make any changes that I am
>>> supposed to mail this list to get input.
>>>
>>
>> This certainly feels like something we should be doing in PhD-land.
>>  "Fixing" the docs would be a nightmare, we wrap everything in s. And
>> remember that HTML isn't the only output format for our docs, any changes
>> to the DocBook structure must take the other media into consideration.
>>
>
> The general impression I had was that I should get more feedback from
> this. Do I have a green light from Peter Cowburn alone or should I be
> waiting for other responses?
>
>
Hold on, you haven't even gotten a "green light" from me!  What is the
ultimate aim here? To get HTML that is "valid"? To fix a rendering bug? If
it's the former, then making PhD spew out "valid" HTML is the task and if
you really want to spend the time working on it, no-one will stop you! If
the latter, I would probably look instead at fixing the broken CSS.

Re: [PHP-DOC] Re: [PHP-WEBMASTER] Uservoice & the new look / docs

[Peter Cowburn]

On 29 June 2013 20:12, Jesus M. Castagnetto  wrote:

> If sharing an admin account is against the TOS and you want to avoid the
> trouble/problem that this can cause, have you considered and older but
> similar tool: Google Moderator. If memory serves, it allowed for anonymous
> posting of ideas and voting.
>

The sharing of the account should not be an issue soon.  Paul has been
talking to the UserVoice people about donating more admin accounts. From
what he said, they were very positive about working with us.

Re: [PHP-DOC] PHD renders and as tags in HTML; this is problematic.

[Peter Cowburn]

On 26 June 2013 21:10, Levi Morrison  wrote:

> 
>
>
> I currently don't know anything about PHD. I'm willing to learn and work
> on this, but my understanding is that before I make any changes that I am
> supposed to mail this list to get input.
>

This certainly feels like something we should be doing in PhD-land.
 "Fixing" the docs would be a nightmare, we wrap everything in s. And
remember that HTML isn't the only output format for our docs, any changes
to the DocBook structure must take the other media into consideration.

Re: [PHP-DOC] Re: [PHP-WEBMASTER] Uservoice & the new look / docs

[Peter Cowburn]

On 25 June 2013 22:58, Hannes Magnusson  wrote:

> On Tue, Jun 25, 2013 at 2:56 PM, Levi Morrison 
> wrote:
> > On Tue, Jun 25, 2013 at 3:43 PM, Paul Dragoonis 
> wrote:
> >>
> >> salathe registered the account, he shared admin details with me to
> >> moderate
> >> and close off issues that I fix.
> >>
> >
> > Not sure what the best way to share these details is, but they really
> ought
> > to be shared somehow.
> >
>
> I'm sure Peter or Paul will share them with you if you need them and
> want them :)
>

Paul won't, because I asked him not to purely for recording purposes.  But
anyone who wants to moderate the feedback needs simply to ask me. Bear in
mind we're probably breaking some ToS on uservoice by sharing an account
between us (the free tier only allows one "agent" (aka admin)).

Also bear in mind that the aim of this is to solicit feedback; the response
so far as been great and on the whole very positive.  It is not supposed to
be a substitute for proper bug reports and tracking, but rather is intended
as a lower barrier for feedback from the community.

In an ideal world anyone choosing an idea/feedback to be worked on should
raise a ticket on bugs.php.net, quoting the idea/feedback text (the URL may
go away at some point) and referencing that bug number when committing.


>
> -Hannes
>

Re: [PHP-DOC] Patch submission - curl_unescape, curl_strerror, curl_reset, fix for curl_escape

[Peter Cowburn]

Hi Adam,

On 14 June 2013 10:29, Adam Kazimierczak  wrote:
>
> Try running this code:
> var_dump(curl_escape(0, 'test'), curl_unescape(0, 'test'));
>
> Both results are NULL and throws E_WARNINGs:
> Warning: curl_escape() expects parameter 1 to be resource, integer given
>

This falls under the "garbage in, garbage out" rule that we historically
don't document. When given incorrect arguments, most PHP functions will
return NULL and raise a warning. See the note about this on
http://php.net/functions.internal

NULL as return on failure is also documented in libcurl docs:
> http://curl.haxx.se/libcurl/c/**curl_escape.html
>

If you check php-src, you'll see the functions return FALSE when cURL's
curl_easy_(un)escape() returns null.

As I said, they're minor issues and you look to be getting the hang of how
things work. I would support giving you commit karma, to be able to push
these changes to the docs yourself.

Cheers,
Peter

Re: [PHP-DOC] Patch submission - curl_unescape, curl_strerror, curl_reset, fix for curl_escape

[Peter Cowburn]

Hi Adam,

On 12 June 2013 22:11, Adam Kazimierczak  wrote:

> Hello Mailing List,
>
> I am attaching a few new patches. Please let me know what do you think
> about them.
>

There are a few *minor* issues, but overall they are looking good.

curl-reset.xml.patch => typos on line 26 and 41
curl-strerror.xml.patch => See Also, do the (raw)urldecode functions need
to be there? Were they copied from curl_(un)escape?
curl-escape.xml.patch => The function returns false on failure
curl-unescape.xml.patch => Again, this returns false on failure



>
> Cheers,
> Adam
>

Re: [PHP-DOC] PHP Manual - Contribution

[Peter Cowburn]

Hi Evan,

On 3 June 2013 20:04, Evan Nabors  wrote:

>  Hello,
>
>  My name is Evan and I am a technical writer that works for Rackspace
> Hosting.
>

Nice to meet you.


>
>  This week I was using the online php manual to assist a customer with a
> PHP script. While looking through the online documentation I came across a
> section providing instructions on "Installing on Cloud Computing
> Platforms". To my dismay Rackspace did not have a presence on this page. I
> am interesting in writing content for the manual that would fill this gape.
> The content would add Rackspace to the list of available cloud providers
> and provide links to our product information and PHP SDK.
>

All gapes must be filled!  I look forward to your contribution.


>
>  I read the getting_started section and noticed the first step was to
> introduce myself. I wanted to get this portion started while I got to work
> on cloning the book and beginning to include my content. Consider this my
> "Hello" fellow tech writers! I look forward to working with you all. Let me
> know if you have any questions/comments/concerns. If not I will get to work
> on cutting a build in the coming days.
>

Similarly, if you have any questions/comments/concerns then feel free to
ask us.


>
>  Link Referenced - http://www.php.net/manual/en/install.cloud.php
>
>  Thanks!
> Evan Nabors
> Rackspace::Cloud('Product Evangelist')
>

Re: [PHP-DOC] Contributions are ready for review

[Peter Cowburn]

On 27 May 2013 19:56, Brad Dewar  wrote:

>
> The 'contribution ready for review' that is about SQLite3::createCollation
> is from me.  createCollation is a relatively new addition to PHP and is
> still undocumented.
>
> Never contributed to the docs before -- any tips on finding a committer?
>

Poke the list… oh, wait. :-)

If you haven't already, you'll need to use the magic word "kitten" in our
IRC channel (#php.doc on Efnet).


>
> Thanks,
> Brad

Re: [PHP-DOC] Error in PHP documentation

[Peter Cowburn]

On 26 May 2013 16:22,  wrote:

> I have been working on it for 2 days, and I still have no clues... The ID
> "class.generator" seems well defined, but the parser cannot find it.
>

I don't see anything for generators in the Italian translation.  You need
the files from http://svn.php.net/viewvc?view=revision&revision=330333 to
be added.



>
> Envoyé à partir de mon terminal mobile BlackBerry®
>
> -Original Message-
> From: Davide Pastore 
> Date: Sun, 26 May 2013 15:58:07
> To: PHP DOC LIST [MAIN]
> Subject: [PHP-DOC] Error in PHP documentation
> Hello to all,
> How can I fix this problem? It may be that the error is caused by the
> documentation in English? I attach the log received from the server.
>
> Thank you for your help.
>
> Davide
>
>

Re: [PHP-DOC] Undocument PHP < 4.3

[Peter Cowburn]

On 19 May 2013 01:04, Jakub Vrana  wrote:

> Hi,
>
> I would like to undocument PHP < 4.3. It means that all mentions like
> "Available since PHP 4.3" would disappear from PHP Manual. Nobody uses
> these version anymore and it just clutters the documentation. We've done
> this previously for PHP < 4. I'll probably leave the mentions in the
> DocBook but comment them out.
>

See the recent discussion on "Undocument PHP4" -
http://php.markmail.org/thread/mldubfcdmdzr3efp

The idea being, move any inline mention of PHP 4 to change log entries. I
think it is still good to keep those change logs available, and to show at
the top of a page whether a function was available in PHP 4 or not with the
version info.


>
> Please let me know your thoughts.
>
> Jakub
>

Re: [PHP-DOC] This PHP Manual build is broken

[Peter Cowburn]

Hi all,

On 5 March 2013 20:12,   wrote:
> The en build of the PHP Manual is broken, so it does not validate or build. 
> Please fix it! ;)

Fixed in r329672.

>
> Attached is the full log
>
> Love,
> The docs.php.net server

Love,
Not the docs.php.net server

Re: [PHP-DOC] strtr return: string or mixed?

[Peter Cowburn]

On 5 February 2013 11:50, Ferenc Kovacs  wrote:
>
> Hi,
>
> We have a note on http://www.php.net/manual/en/functions.internal.php
> "Note: If the parameters given to a function are not what it expects, such
> as passing an array where a string is expected, the return value of the
> function is undefined. In this case it will likely return NULL but this is
> just a convention, and cannot be relied upon."
> We introduced a new parameter parsing API, which made this behavior more
> widely supported:
> http://php.net/manual/en/migration53.incompatible.php
> "The newer internal parameter parsing API has been applied across all the
> extensions bundled with PHP 5.3.x. This parameter parsing API causes
> functions to return NULL when passed incompatible parameters. There are some
> exceptions to this rule, such as the get_class() function, which will
> continue to return FALSE on error."
>
> I think that the current documentation is lacking in this regard, but I'm
> not sure which would be the best solution to address this.
>

Whatever happens, we don't want to start adding phrases like "this
function will return null and issue an E_WARNING if you feed rubbish
into it" to any (nearly all!) functions.  Expanding upon that short
paragraph mentioned above might be nice, but I would really dislike
for us to start "fixing" almost every single function's return types
(they would all return "mixed").  I'm sure we've discussed this
on-list previously, I'll take a look at the history.

[PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/en/trunk/reference/spl/splfileobject/ tostring.xml

[Peter Cowburn]

On 30 January 2013 09:37, Ferenc Kovacs  wrote:
>
> hi,
>
> could you please link the relevant page about this?
>
> 
>
> Before I commited the change, I looked around, and every other alias under
> spl had the method synapsis with the exception of
> splfileobject/getcurrentline.xml(which should be also fixed depending on the
> outcome of this discussion):
>
> splobjectstorage/offsetunset.xml
> splobjectstorage/offsetexists.xml
> splobjectstorage/offsetset.xml
> splqueue/enqueue.xml
> splqueue/dequeue.xml
>
> So I think that the method should be listed in the synopsis (to avoid
> confusion), there are existing precedences for aliases between class methods
> having methodsynopsis and there is nothing (or at least I couldn't find)  in
> the docs related to this, so nothing which would prohibit the methodsynopsis
> usage in this case.
>
> What do you think?
>

The doc howto (usually at http://doc.php.net/php/dochowto which is
broken, the source is in doc-base/howto) says that aliases should not
have the synopsis and should only direct readers to the aliased
function/method. [1]

We break this rule in many SPL doc pages already, sometimes on
purpose.  It probably happens elsewhere too. The reasons are twofold:
1. many of the pages are little more than skeleton docs so have the
normal method page structure rather than the proper alias one; 2. It's
nice to have the method synopsis there since then those methods are
then listed in the class synopsis.

Should we think about amending the howto with regards to maybe adding
in a synopsis for methods? Obviously that works against us in terms of
maintenance (more places to change should the method signatures
change) and cleanliness (the alias page's job is to redirect to the
appropriate fully-documented method).

Or, is there a way to get these aliases showing up in the class
synopsis method list whilst keeping the alias page without a method
synopsis?

[1] 
http://svn.php.net/viewvc/phpdoc/doc-base/trunk/howto/working.xml?view=markup#l343

Re: [PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/en/trunk/ .travis.yml

[Peter Cowburn]

On 21 January 2013 00:48, Hannes Magnusson  wrote:
>
> I assume that much, but... and what?
> Do we get a mail on build failure? Does it notify the author who broke
> the build?
> Whats the purpose?
>

Currently, the author/committer (the same person, as we're using SVN)
will get an email if they break the build. Being the repository owner,
I also get that email.

It could be set up to mail phpdoc if we prefer. This was deliberately
turned *off* for php-src, but since we have a less broken build it
might not spam the list too much.

Re: [PHP-DOC] PHP.net tutorials improvements

[Peter Cowburn]

On 1 January 2013 13:24, Florin Razvan Patan  wrote:
>
> How do you propose we start working on this? Should we get either a
> repository on git/github with a tutorials section or maybe a wiki install
> of some sorts?
>

Pieter (and others?) has already been working in this area for a
while, perhaps you could join in?

See https://github.com/PeeHaa/php-net-tutorial

Re: [PHP-DOC] Contributions are ready for review

[Peter Cowburn]

Howdy!

On 12 November 2012 13:00,   wrote:
> Hello PHP EN Documentation team,
>
> There are contributions within the online editor queue for this language.
> Please review, then commit or delete these patches.

I have gone through the list of patches and reviewed/trashed/committed
them. All that remains, at the time of writing, is Rafael's date
changes (that I can't do anything with).

Thanks to everyone for their contributions.

Re: [PHP-DOC] This PHP Manual build is broken

[Peter Cowburn]

On 21 September 2012 12:10,   wrote:
> The en build of the PHP Manual is broken, so it does not validate or build. 
> Please fix it! ;)

Fixed in r327738.

>
> Attached is the full log
>
> Love,
> The docs.php.net server

Love,
 Peter

Re: [PHP-DOC] My karma is too low

[Peter Cowburn]

On 21 August 2012 13:25, Andrew Faulds  wrote:
> On 21/08/12 13:23, pasdav...@gmail.com wrote:
>>
>> Il 21/08/2012 14.08, Andrew Faulds ha scritto:
>>>
>>> Just submit the patch and the mailing list folks can review it for
>>> inclusion.
>>
>> Ok I attach the .patch file. I hope this is the right procedure.

Attaching the patch file in an email to the list is absolutely fine.
Using the online editor is not a requirement.

Davide, I have committed your patch. Thanks!

Re: [PHP-DOC] phpdoc svn access grant for : mariuz

[Peter Cowburn]

Hi Marius,

On 20 August 2012 13:20, marius adrian popa  wrote:
> I need to make some corrections on the firebird pdo documentation
>

You already have full phpdoc karma.

Re: [PHP-DOC] VCS Account Request: stanv

[Peter Cowburn]

On 9 August 2012 09:21, Stan Vass  wrote:
> I want to maintain the documentation and punch the person who designed this 
> form.
>

This may be an unusual response to an account request but I would not
advise giving an account to Stan at this point in time, for the
following reasons.

1. His main reasons for wanting an account is because he "lost"
changes made in the OE as an anonymous user, and because having an
account means his name will be "attached" to his contributions.
2. He has shown a sharp lack of regard for the processes involved and
refuses to follow instructions unless pressed.
3. He has, thus far, no patches to show any basic level of competence
in documentation writing.
4. He appears to back down from even the smallest obstacle (filing in
the account request form took many attempts over time), which does not
bode well for working with SVN/Git (which he has already shown a lack
of desire to set up to provide patches) or learning the ins and outs
of authoring the documentation.

I must say, at this stage, that Stan does show a desire to improve the
documentation and has mentioned several places where he would like to
improve things. However, he seems overly focussed on getting an
account rather than actually getting some patches committed; and has
actively refused to submit patches.

Oh, and he didn't mention liking kittens in the account request.

My suggestion would be to keep the account request on hold until such
a time as we are more confident in his ability and willingness to
contribute in a positive manner within the project.

Re: [PHP-DOC] [DOC-EN] - Your documentation is broken

[Peter Cowburn]

On 6 August 2012 21:00,   wrote:
> Your documentation is broken. The build is done on Friday.
>
> Please, try to fix it *quickly*.

The problem was fixed yesterday, the sources on edit.php.net must be
out of date. The documentation does build at the moment.

[PHP-DOC] Re: [PHP-WEBMASTER] Singleton PHP page in english from Netherland is not working

[Peter Cowburn]

On 17 June 2012 15:29, Daniel Brown  wrote:
> On Jun 17, 2012 8:30 AM, "Altaf Samnani"  wrote:
>>
>>
>> Hi  I was in india and was accessing the page of singleton and it was not
> working now i migrated to Netherlands and trying to access the page and i
> am not able to access that.
> http://php.net/manual/en/language.oop5.patterns.php
> Regards Altaf S
>
> Looks like it was removed from the English language module entirely, not
> just for IN or NL mirrors.
>
> CC'ing the Docs list for someone else to be able to help you out.
>

The "patterns" chapter of the PHP 5 OOP part of the manual was removed
[1] in mid-May.  Jakub's reasoning for deletion, directly from his
commit message, is:

I have a very strong feeling that this chapter doesn't belong to
the PHP Manual.
It doesn't document the language but only some usage of it.
It is vastly incomplete and the longest part is warning about
using Singleton.
I have no problem with including the examples somewhere else
(probably to chapter about static methods).
But it causes more harm than benefit as it is.

I hope that provides an answer for you.

Re: [PHP-DOC] ext/mysql updates (~deprecated)

[Peter Cowburn]

On 4 June 2012 19:23, Nikita Popov  wrote:
> What concerns me a bit is that the mysql soft deprecation notices are
> more intrusive than the "real" deprecation notices. Could we use
> something similar to show alternatives for other (really) deprecated
> functions too? (Thinking of ereg and stuff)

Absolutely, yes.  Even after all these years, it is still common to
hear people asking about the "new" deprecated message when they use
ereg() and friends, and what to do to make the error go away!  We do
have the Big Red Box near the top of the page for ereg(), but even
this does not a) link to alternatives, nor b) link to anywhere helping
to guide people on how to migrate their code: all they get is,
"Relying on this feature is highly discouraged."

Re: [PHP-DOC] ext/mysql updates (~deprecated)

[Peter Cowburn]

On 2 June 2012 12:53, Hannes Magnusson  wrote:
>
> Yep. +1 from me.
>

Excellent. I've committed your patches for PhD, the
mysql_affected_rows() docs change, and mine for phpweb.  I've also
opened a ticket to track these changes (and conveniently forgot to
reference it in the commits!) at https://bugs.php.net/62213

I guess, if the above hasn't caused everything to explode, the next
step is to roll out the docs changes for the rest of the ext/mysql
functions (Philip?).  Also, do we want to get this into a PhD release;
I believe this was mentioned earlier?

Re: [PHP-DOC] ext/mysql updates (~deprecated)

[Peter Cowburn]

On 1 June 2012 01:03, Philip Olson  wrote:
>
> We could tweak it later but ultimately we can make ext/mysql the
> initial test case for deprecating an extension both softly and,
> err, for real.

We had a chat on IRC and there seemed to be more support for making
the "Suggested alternatives" box inline, beneath the "Description"
section.  Having the box floating (and fixed position) causes issues
with reading (or not!) what is underneath it.

There has also been some support, only half-joking, for going all out
like http://i.imgur.com/8BhK9.png

Either way, support definitely seems in favour being pretty
in-your-face, with a big warning box somewhere.

Attached are patches against phpweb (current and prototype themes) and
the English docs (for mysql_affected_rows() only). The phpweb patch
was mangled from Hannes' earlier patch, so could do with some keen
eyes to go over it to see if it needs more cowbell.  Also, Hannes' phd
patch should be used in conjunction.

Here are some screenshots.
 - php.net      http://i.imgur.com/MmVn7.png
 - prototype   http://i.imgur.com/Emj8f.png


phpweb-deprecate.patch
Description: Binary data


phpdoc-deprecate.patch
Description: Binary data

Re: [PHP-DOC] Broken URL entities report

[Peter Cowburn]

On 17 April 2012 13:00,  wrote:

>
> Below is a list of URL entities that are experiencing fatal errors:
>
> UNKNOWN_HOST
> - &url.caudium; : http://caudium.net/
>
>
Fixed in r325265.

[PHP-DOC] Re: [PHP-CVS] svn: /php/php-src/branches/PHP_5_4/ UPGRADING

[Peter Cowburn]

Hi docs folks,

What are your thoughts on how to treat the
get_magic_quotes_(gpc|runtime) functions, in the documentation.
Traditionally we mark functions as deprecated if they're deprecated in
the code (e.g. PHP_DEP_FE), but that's not the case for these two.

Should we just say in the change log that they'll always return false,
or should the term "deprecated" be used?

Peter

On 22 November 2011 13:16, Pierre Joye  wrote:
> they are, we only not raise notices or warnings anymore to keep the
> user experience at a good level. So please keep them in here :)
>
> On Tue, Nov 22, 2011 at 2:11 PM, Pierrick Charron  wrote:
>> pierrick                                 Tue, 22 Nov 2011 13:11:20 +
>>
>> Revision: http://svn.php.net/viewvc?view=revision&revision=319679
>>
>> Log:
>> Those functions are not deprecated (r319249 #55371)
>>
>> Bug: https://bugs.php.net/55371 (Closed) get_magic_quotes_gpc() throws 
>> deprecation warning
>>
>> Changed paths:
>>    U   php/php-src/branches/PHP_5_4/UPGRADING
>>
>> Modified: php/php-src/branches/PHP_5_4/UPGRADING
>> ===
>> --- php/php-src/branches/PHP_5_4/UPGRADING      2011-11-22 12:47:49 UTC (rev 
>> 319678)
>> +++ php/php-src/branches/PHP_5_4/UPGRADING      2011-11-22 13:11:20 UTC (rev 
>> 319679)
>> @@ -258,8 +258,6 @@
>>  7. Deprecated
>>  =
>>
>> -- get_magic_quotes_gpc()
>> -- get_magic_quotes_runtime()
>>  - mcrypt_generic_end()
>>  - mysql_list_dbs()
>>
>>
>>
>> --
>> PHP CVS Mailing List (http://www.php.net/)
>> To unsubscribe, visit: http://www.php.net/unsub.php
>>
>
>
>
> --
> Pierre
>
> @pierrejoye | http://blog.thepimp.net | http://www.libgd.org
>
> --
> PHP CVS Mailing List (http://www.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

Re: [PHP-DOC] SVN Account Request: gooh

[Peter Cowburn]

On 8 November 2011 16:23, Philip Olson  wrote:
>
> On Nov 8, 2011, at 8:07 AM, Gordon Oheim wrote:
>
>> contributing to the english and german documentation
>
> Greetings Gordon,
>
> This account has been approved with phpdoc karma granted, welcome to the PHP 
> documentation team! :)

Thanks Philip. Welcome to the team, Gordon. :)

>
> Regards,
> Philip

Re: [PHP-DOC] mixed parameters proposal

[Peter Cowburn]

Hi Geoffray,

On 5 October 2011 10:29, Geoffray Warnants  wrote:
> Dear PHPDOC Team,
>
> I would like to hear what you have to say about the convention actually used
> in the PHP manual to
> describe "mixed" values, I mean parameters (or return values) that could
> have multiple datatypes.
>
> I don't like them so much for some reasons :
> - The first think I read about a PHP function in the documentation is its
> prototype. The prototype must describe input/output parameters as accurately
> as possible (data type, default value, reference, ...) without having to
> read the full attached doc.
> - The PHP Documentation is often integrated in latest IDE. They instantly
> show us nice help tooltips with the complete protoype of the PHP function we
> are writing. But it don't tell me what's expected if some parameters are
> "mixed".
>
> As an example, I will use strpos() function :
>
> The documentation says strpos returns an integer or FALSE if an error
> occured. OK, but the prototype only tells me it returns an integer :
>
> int strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
>
> To be correct and respect the current convention, we could use the "mixed"
> type as the return value.
>
> mixed strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
>
> It is then strictly more accurate but less intuitive : when I read that
> prototype without the attached doc (like it is in some IDE), I'm not able to
> see clearly the return type I will get : even more confusing !
> So why not to use the convention used in some documentation tools like
> phpDocumentor : a value can have multiple datatypes by delimiting them with
> the pipe. So it will become :
>
> int|bool strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
>
> It is great by not fully intuitive : when reading "bool" in my IDE I may
> think the function will also return "true" in some case...
> So, a custom convention I suggest would be :
>
> int|false strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
>
> Assuming many PHP functions returns the bool FALSE only if an error occured,
> I think that syntax tells me everything I need to know. The same logic could
> be applied to parameters.
>
> What do you think ?

Most functions will also return NULL if you provide invalid
parameters, for example, strpos("cake"). Should the prototype reflect
this too? int|false|null strpos ( ...


>
> Regards,
> Geoffray
>

[PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/en/trunk/reference/mysqli/mysqli/ real-escape-string.xml

[Peter Cowburn]

On 22 September 2011 15:54, Philip Olson  wrote:
>
 + 
 +  &reftitle.notes;
 +  
 +   
 +    For those accustomed to using 
 mysql_real_escape_string,
 +    note that the arguments of 
 mysqli_real_escape_string
 +    differ from what mysql_real_escape_string 
 expects.
 +    The link identifier comes first in
 +    mysqli_real_escape_string, whereas the string to 
 be escaped
 +    comes first in mysql_real_escape_string.
 +   
 +  
 + 
>>>
>>>
>>> That is true with all the mysql[i]_*() functions.
>>> mysql_ takes the (optional) link identifier as the latter parameter,
>>> while the mysqli_ ones require it - and it is the first parameter..
>>>
>>> With that in mind, is this really needed?
>>
>> Good question. Lets see what the phpdoc list thinks. :)
>
> My initial reaction sees two options:
>
>  (1) Add a general comment within the Introduction* about this
>  (2) Begin the mysql->mysqli migration guide, by starting with this
>
> I lean towards (2).

That sounds like a plan. Something like this certainly would feel most
at home within a migration guide rather than clogging up many
functions' notes sections.

>
> Regards,
> Philip
>
> * http://php.net/manual/en/intro.mysqli.php

[PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/en/trunk/reference/mysqli/mysqli/ real-escape-string.xml

[Peter Cowburn]

On 22 September 2011 15:39, Hannes Magnusson  wrote:
> On Thu, Sep 22, 2011 at 12:23, Peter Cowburn  wrote:
>> salathe                                  Thu, 22 Sep 2011 10:23:50 +
>>
>> Revision: http://svn.php.net/viewvc?view=revision&revision=317146
>>
>> Log:
>> note on parameter order (doc #55757, thanks Sherif Ramadan)
>>
>> Bug: https://bugs.php.net/55757 (Assigned) mysqli vs. mysql_* use of real 
>> escape string
>>
>> Changed paths:
>>    U   phpdoc/en/trunk/reference/mysqli/mysqli/real-escape-string.xml
>>
>> Modified: phpdoc/en/trunk/reference/mysqli/mysqli/real-escape-string.xml
>> ===
>> --- phpdoc/en/trunk/reference/mysqli/mysqli/real-escape-string.xml      
>> 2011-09-22 09:58:45 UTC (rev 317145)
>> +++ phpdoc/en/trunk/reference/mysqli/mysqli/real-escape-string.xml      
>> 2011-09-22 10:23:50 UTC (rev 317146)
>> @@ -137,6 +137,20 @@
>>   
>>  
>>
>> + 
>> +  &reftitle.notes;
>> +  
>> +   
>> +    For those accustomed to using 
>> mysql_real_escape_string,
>> +    note that the arguments of 
>> mysqli_real_escape_string
>> +    differ from what mysql_real_escape_string expects.
>> +    The link identifier comes first in
>> +    mysqli_real_escape_string, whereas the string to 
>> be escaped
>> +    comes first in mysql_real_escape_string.
>> +   
>> +  
>> + 
>
>
> That is true with all the mysql[i]_*() functions.
> mysql_ takes the (optional) link identifier as the latter parameter,
> while the mysqli_ ones require it - and it is the first parameter..
>
> With that in mind, is this really needed?

Good question. Lets see what the phpdoc list thinks. :)

>
> -Hannes
>
> --
> PHP Documentation Commits Mailing List (http://www.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

Re: [PHP-DOC] Patch to Add AMQP Examples

[Peter Cowburn]

On 26 August 2011 17:05, Bradley Holt  wrote:
> Philip,
>
> On Thu, Aug 25, 2011 at 8:35 PM, Philip Olson  wrote:
>>
>> On Aug 25, 2011, at 11:14 AM, Bradley Holt wrote:
>>
>>> Hi,
>>>
>>> Attached is a patch to add examples to the documentation for
>>> AMQPQueue::get and AMQPQueue::ack.
>>
>>
>> Hello Bradley,
>>
>> Looks good. A few minor issues:
>>
>>  - Use  for all methods. Sometimes you used .
>>   Both work but, well, I did say "minor" issues :)
>>  - PHP code indentation should be 4 spaces instead of the XML
>>   friendly 1
>>
>
> Got it. I was following the examples set elsewhere in AMQP
> documentation. I guess updating those to follow the proper standard is
> another task that could be done :-)

Absolutely. :)

>
>> Also, your SVN account request has been approved with phpdoc karma
>> granted, welcome to the PHP Documentation team! :)
>>
>
> Woo-hoo!
>
> Should I apply these last couple of patches that I've sent in, now
> that I've got commit access?

Yes! That's what the karma is there for.  Any questions just ask, here
or on IRC.  Welcome to the documentation team!

>
> Thanks,
> Bradley
>
>> Regards,
>> Philip
>>
>>
>>
>

Re: [PHP-DOC] Patch to Add AMQP Examples

[Peter Cowburn]

Hi Bradley,

On 25 August 2011 19:14, Bradley Holt  wrote:
> Hi,
>
> Attached is a patch to add examples to the documentation for
> AMQPQueue::get and AMQPQueue::ack.

Would you mind attaching future patches as .txt files? Gmail lets me
view those in the browser, but requires me to download .patch files
before viewing them.

(And, I thought only .txt files were accepted on the list. But that's
clearly not the case!)

>
> Thanks,
> Bradley
>

Re: [PHP-DOC] Time wasting : Silly thing just spotted.

[Peter Cowburn]

On 20 July 2011 15:06, Richard Quadling  wrote:
> Hi.
>
> For a laugh, I thought I try and build all the langs. Obviously, a
> whole load fail.
>
> But one failed in a way that took a little while to figure out.
>
> configure.php's output ...
>
> configure.php: $Id: configure.php 310808 2011-05-06 16:11:39Z bjori $
> PHP version: 5.3.7RC4-dev
>
> Checking for source directory... D:\Manual\PHP\doc-all\doc-base
> Checking for output filename... D:\Manual\PHP\doc-all\doc-base\.manual_no.xml
> Checking whether to include CHM... no
> Checking for PHP executable... C:/PHP_5_3/php.exe
> Checking for language to build...
> error: Using '--with-lang=' or '--without-lang' is just going to cause 
> trouble.
>
>
> Can you guess the command line?

Nice bug, poor Norwegians. :(

>
>
>
> --
> Richard Quadling
> Twitter : EE : Zend : PHPDoc
> @RQuadling : e-e.com/M_248814.html : bit.ly/9O8vFY : bit.ly/lFnVea
>

Re: [PHP-DOC] SVN Account Request: samhastings

[Peter Cowburn]

On 26 June 2011 15:38, Philip Olson  wrote:
>
> On Jun 24, 2011, at 6:20 AM, Sam Hastings wrote:
>
>> Maintaining the documentation
>
> Hello Sam,
>
> Contributing begins with patches, which soon turns into SVN access. In other 
> words, you should check out the PHP documentation source files, fix things, 
> then submit a patch or three. Once people realize that you're a sane person 
> who wants to contribute, then you'll gain SVN commit access.

Just a note to say that the sane part is optional, it is the
demonstrated willingness to contribute that is important. Good luck.
:)

>
> And this howto is a good place to start:
>
>  http://wiki.php.net/doc/howto
>
> As an example starting point, the following script checks out the doc sources 
> and setups a local doc environment:
>
>  $ wget 
> http://svn.php.net/repository/phpdoc/doc-base/trunk/scripts/create-phpdoc-setup.php
>  $ php create-phpdoc-setup.php -l en -b ~/phpdocs
>  $ cd ~/phpdocs/doc-en
>  $ vim en/stuff.xml
>  $ php doc-base/configure.php
>
> Please ask questions here or in IRC (#php.doc on efnet), and talk to you 
> soon! :)
>
> Regards,
> Philip
>
>

Re: [PHP-DOC] PhD and configure.php optimizations

[Peter Cowburn]

On 27 April 2011 13:58, Hannes Magnusson  wrote:
> Hi all
>
>
> I've been working on some optimizations for PhD and configure.php the
> past few days..

You're my hero-of-the-week... I render bits and pieces of the docs *a
lot* (as everyone should) so taking the turn-around time from 8
minutes to 8 seconds will make life a heckofalot easier.

>
> Some changes;
> - The PhD indexing should be "blazingly" fast now (~2minutes shaved
> off on my laptop) , compared to the current release
> - The rendering should start faster now (~20sec shaved off on my laptop)
> - configure.php now has a developers (--generate) option, similar to --partial
>
>
> The configure.php --generate option takes a *filename* as an argument,
> and will create a .manual.xml file based on that filename.
> You would usually pass in en/reference//book.xml as the
> filename, or other chunk containers.
>
> This option will make configure.php eat heckofalot less ram, improve
> its performance - and at last, but not least, reduce the phd rendering
> time maaassively.
>
> Do note: passing --generate will turn on "force save" because the
> document will usually not validate (due to missing IDREFs), so you
> will always get the .manual.xml (unless you have a major xml error in
> your doc).
>
>
> All this takes us alot closer to be able to provide "live preview" in PhD OE..
> The "whole shebang" (configure.php, phd indexing, phd rendering) for
> one book (mysqli, for example) takes my laptop less then 7seconds[1]
> :D

Very exciting, having folks be able to see a preview of their changes
has been one of the most requested features from the people I've asked
to use the online editor. :)

>
>
> -Hannes
>
> [1] http://pastebin.com/fzzDUedw
>

Re: [PHP-DOC] This PHP Manual build is broken

[Peter Cowburn]

On 27 January 2011 06:15, Apache  wrote:
> The  build of the PHP Manual is broken, so it does not validate or build. 
> Please fix it! ;)

Fixed in r30. Thanks Apache! ;)

>
> Love,
>        The docs.php.net server
>

Love,
        Peter

Re: [PHP-DOC] Contributions are ready for review

[Peter Cowburn]

On 10 January 2011 13:00,   wrote:
>
> Hello PHP EN Documentation team,
>
> There are contributions within the online editor queue for this language.
> Please review, then commit or delete these patches.

For the "Patches for review" section, is there any way for us to apply
them? In the editor, I can see the diffs/changes for joey and conf's
patches but not commit them.  When opening the changed files in the
editor, I cannot save them as my own work in progress (to then
commit).

As for the "Work in progress" section, I cannot see any of them in the
editor... maybe it is intentional, but if so then why list them here?

(If it makes a difference, I logged in for the English language as a
VCS user, not anonymous.)

>
>    Work in progress :
>    ---
>        * (new) On 2010-05-24 16:36:37 by markskilbeck : 
> en/reference/cairoimages/-
>        * (new) On 2010-08-03 11:57:22 by mfonda : 
> en/reference/array/functions/key-exists.xml
>        * (new) On 2010-08-10 04:48:00 by dragoonis : 
> en/reference/network/functions/http-response-code-
>        * (new) On 2010-08-10 05:32:52 by dragoonis : 
> en/reference/network/functions/http-response-code/
>        * (new) On 2010-09-11 05:30:24 by anonymous #476 : en/referencessdeep/-
>        * (new) On 2010-09-12 15:15:46 by anonymous #478 : en/chapters1/-
>        * (update) On 2010-07-23 23:24:22 by anonymous #249 : 
> en/reference/mysqli/mysqli/real-connect.xml
>        * (update) On 2010-08-03 11:58:40 by mfonda : 
> en/reference/array/entities.functions.xml
>        * (update) On 2010-09-13 17:18:18 by danbrown : 
> en/reference/sdo/setup.xml
>        * (update) On 2010-09-26 07:22:48 by anonymous #532 : 
> en/reference/fileinfo/functions/mime-content-type.xml
>        * (update) On 2010-09-29 09:19:34 by anonymous #539 : 
> en/features/commandline.xml
>        * (update) On 2010-10-08 13:27:08 by anonymous #569 : 
> en/reference/stream/streamwrapper/stream-open.xml
>        * (update) On 2010-10-10 13:35:59 by anonymous #478 : 
> en/reference/amqp/amqpconnection.xml
>        * (update) On 2010-10-12 01:36:47 by anonymous #283 : en/extensions.ent
>        * (update) On 2010-10-26 04:56:37 by anonymous #619 : 
> en/reference/filesystem/functions/fnmatch.xml
>        * (update) On 2010-12-06 17:11:48 by anonymous #808 : en/faq/com.xml
>        * (update) On 2010-12-06 23:58:59 by anonymous #810 : 
> en/contributors.xml
>        * (update) On 2010-12-16 08:56:58 by anonymous #916 : 
> en/reference/strings/functions/echo.xml
>        * (update) On 2011-01-08 10:04:57 by anonymous #1091 : 
> en/language-defs.ent
>
>
>    Patches for review :
>    ---
>        * (update) On 2010-10-15 08:28:58 by conf : en/language/types.xml
>        * (update) On 2010-10-19 04:38:43 by conf : en/language/types/array.xml
>        * (update) On 2010-11-24 14:27:46 by joey : 
> en/reference/pcre/pattern.syntax.xml
>
>
>
> --
> https://edit.php.net/
> This email is send automatically by the Php Docbook Online Editor.
>

[PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/doc-base/branches/gtk-docgen/scripts/docgen/ docgen.php

[Peter Cowburn]

On 17 November 2010 02:52, Justin Martin  wrote:
> frozenfire                               Wed, 17 Nov 2010 02:52:49 +
>
> Revision: http://svn.php.net/viewvc?view=revision&revision=305431
>
> Log:
> Very preliminary mod of docgen.php which uses the PHP-GTK sources to bypass 
> lack of Reflection data.

Is there any reason why these gtk-related changes cannot happen on trunk?

>
> Changed paths:
>    U   phpdoc/doc-base/branches/gtk-docgen/scripts/docgen/docgen.php
>
> Modified: phpdoc/doc-base/branches/gtk-docgen/scripts/docgen/docgen.php
> ===
> --- phpdoc/doc-base/branches/gtk-docgen/scripts/docgen/docgen.php       
> 2010-11-17 02:50:01 UTC (rev 305430)
> +++ phpdoc/doc-base/branches/gtk-docgen/scripts/docgen/docgen.php       
> 2010-11-17 02:52:49 UTC (rev 305431)
> @@ -70,6 +70,7 @@
>        -c,--class      -- class name
>        -e,--extension  -- extension name
>        -f,--function   -- function name
> +       -g,--gtk        -- specify the PHP-GTK source directory
>        -h,--help       -- show this help
>        -i,--include    -- includes a PHP file
>        (shortcut for: php -dauto_prepend_file=streams.php docgen.php)
> @@ -832,8 +833,35 @@
>
>                        write_doc($extension, DOC_EXTENSION);
>
> -                       foreach ($extension->getClasses() as $class) {
> -                               gen_docs($class->name, DOC_CLASS);
> +                       if($OPTION['gtk']) {
> +                               $classes = array();
> +                               $dirsep = DIRECTORY_SEPARATOR;
> +                               $data = array_merge(
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}gtk+{$dirsep}atk.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}gtk+{$dirsep}gdk.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}gtk+{$dirsep}gtk.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}extra{$dirsep}gtkextra.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}html{$dirsep}html.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}libglade{$dirsep}libglade.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}libsexy{$dirsep}sexy.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}mozembed{$dirsep}mozembed.defs"),
> +                                       
> file("{$OPTION['gtk']}{$dirsep}ext{$dirsep}sourceview{$dirsep}sourceview.defs")
> +                               );
> +                               foreach ($data as $line) {
> +                                       preg_match("/(?:of-object 
> \")(\w*)(?:\")/", $line, $matches);
> +                                       if($matches) $classes[] =  
> $matches[1];
> +                               }
> +                               $classes = array_unique($classes);
> +
> +                               foreach ($classes as $classtmp) {
> +                                       if(!class_exists($classtmp)) continue;
> +                                       $class = new 
> ReflectionClass($classtmp);
> +                                       gen_docs($class->name, DOC_CLASS);
> +                               }
> +                       } else {
> +                               foreach ($extension->getClasses() as $class) {
> +                                       gen_docs($class->name, DOC_CLASS);
> +                               }
>                        }
>
>                        foreach ($extension->getFunctions() as $function) {
> @@ -1005,6 +1033,7 @@
>  $OPTION['method']       = NULL;
>  $OPTION['class']        = NULL;
>  $OPTION['function']  = NULL;
> +$OPTION['gtk']          = NULL;
>  $OPTION['output']       = getcwd() . '/output';
>  $OPTION['verbose']   = true;
>  $OPTION['quiet']        = false;
> @@ -1033,6 +1062,7 @@
>        'class:'                => 'c:', /* classname */
>        'extension:'    => 'e:', /* extension */
>        'function:'     => 'f:', /* function */
> +       'gtk:'                  => 'g:',  /* gtk */
>        'method:'               => 'm:'  /* method */
>  );
>
> @@ -1065,6 +1095,10 @@
>                case 'function':
>                        $OPTION['function'] = $value;
>                        break;
> +               case 'g':
> +               case 'gtk':
> +                       $OPTION['gtk'] = $value;
> +                       break;
>                case 'm':
>                case 'method':
>                        if (!array_key_exists('c', $options) && 
> !array_key_exists('class', $options)) {
>
>
> --
> PHP Documentation Commits Mailing List (http://www.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub.php
>

Re: [PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/en/trunk/reference/spl/ recursivedirectoryiterator.xml

[Peter Cowburn]

On 19 August 2010 12:02, Mark Wiesemann  wrote:
> Hi Peter,
>
>> salathe                                  Wed, 18 Aug 2010 11:43:15 +
>>
>> Revision: http://svn.php.net/viewvc?view=revision&revision=302434
>>
>> [...]
>> Modified: phpdoc/en/trunk/reference/spl/recursivedirectoryiterator.xml
>> ===
>> --- phpdoc/en/trunk/reference/spl/recursivedirectoryiterator.xml      
>> 2010-08-18 11:33:01 UTC (rev 302433)
>> +++ phpdoc/en/trunk/reference/spl/recursivedirectoryiterator.xml      
>> 2010-08-18 11:43:15 UTC (rev 302434)
>> [...]
>>
>> +
>> + 
>
>  doesn't seem to be allowed here:

Yep, my bad. I placed it outside of the  that it should
have been inside of.  It has now been moved and also renamed to
 to match the other class-level changelog that I spotted
(ArrayObject).

>
> ERROR (file:/en/reference/spl/recursivedirectoryiterator.xml:124:4)
> 
> ^
>  Element classref content does not follow the DTD, expecting (((title |
>  titleabbrev | subtitle)* , info?) , partintro? , (phpdoc:varentry | 
> refentry)*),
>  got (title titleabbrev partintro refsect1 refentry refentry refentry refentry
>  refentry refentry refentry refentry )
>
> Regards,
> Mark

Re: [PHP-DOC] PECL/Memcache documentation

[Peter Cowburn]

Hi Brian,

On 17 June 2010 21:34, Brian Moon  wrote:
>> The patch deletes the timeout parameter from the parameters
>> documentation, yet the parameter exists in the function signature.
>> Regardless of how useful a parameter is, the documentation should
>> match the signature/behaviour which means leaving it (but changing
>> its description). Right?
>
> Ok, new patch attached. I can live with documented but deprecated.
>
>> Also,  for $timeout should be 0 in the
>> associated.
>
> I didn't touch the methodparam block. So, I am not sure what you are talking
> about.

The default $timeout sent over to memcached, if none was specified, is
zero (is it?). If that is the case, the docs need to reflect that
(even if the value isn't/shouldn't ever be used) with something like
``...timeout0``
-- of course, if there is no default value, then there is no need for
an initializer element.

>
>> And lastly, changes in behavour should be described in the
>> role within the methods docs.
>
> And here you really lost me. I have not done PHP doc work in 10 years so
> bear with me. I am sure if you work on them every day this makes sense, but
> it reads like Java to me. ;)

Presumably, the $timeout parameter worked at some point? The
changeover from being accepted to being deprecated/unsupported needs
to be documented in a "Changelog" block[1] so that folks using an old
version (god forbid) can see how things were rather than how things
are.

[1] See an example: http://wiki.php.net/doc/skeletons/function

>
> Brian.
>

Re: [PHP-DOC] broken build notification proposal

[Peter Cowburn]

Hi Yannick

On 23 June 2010 18:36, Yannick Torrès  wrote:
> 2010/6/23 Peter Cowburn 
>>
>> On 22 June 2010 19:08, Philip Olson  wrote:
>> > Hello all,
>> >
>> > This proposal proposes the following:
>> >
>> >  (1) Email the translation lists (doc-$lang) when a translation build is
>> > broken
>> >   (A) Active translations daily
>> >   (B) Inactive translations weekly
>> >  (2) Email phpdoc@ when the English build is broken (daily)
>> >
>> > I don't expect many emails ;) Sound fine? Thoughts on improving this
>> > idea?
>>
>> Sounds great!  My only "improvement" would be to perhaps run the build
>> test immediately after a commit (perhaps only email the author or a
>> selected list of folks?) if that is feasible.
>
> There are 2 points who let me know it's not a good idea :
> * The build process consume some memory and there is (can be) a "lot of
> commit" via the editor

There is no requirement that the build process take place on the box
that runs the editor, is there? I've been playing around with farming
this sort of task out to "the cloud" but I'm not sure how folks would
feel with non-php.net hardware. Then again, what does it matter
between getting a broken build message soon after a commit, versus
getting one within 24 hours of it being broken... daily (or even less
frequent for less active translations) may well be "good enough".

> * If 2 users who work on the same translations commit, we must put in a
> pending queue the build process
>
>
>>
>>  Folks should be
>> checking the build before committing (I guess that cannot be the case
>> with the online editor), but immediately after is the next best thing.
>
> We simply can't do that. But we introduice some weeks ago a new
> functionnality witch allow user to check the xml of his file before saving.
> As I have said when I put this online, we can imagine to not save a file who
> have some xml syntax error.
>
>>
>> >
>> > Yannick added code to do this within web/doc-editor/, and it would
>> > happen via cron on the editor box (pb11.php.net).
>> >
>> > Regards,
>> > Philip
>> >
>> >
>
>

Re: [PHP-DOC] broken build notification proposal

[Peter Cowburn]

On 22 June 2010 19:08, Philip Olson  wrote:
> Hello all,
>
> This proposal proposes the following:
>
>  (1) Email the translation lists (doc-$lang) when a translation build is 
> broken
>   (A) Active translations daily
>   (B) Inactive translations weekly
>  (2) Email phpdoc@ when the English build is broken (daily)
>
> I don't expect many emails ;) Sound fine? Thoughts on improving this idea?

Sounds great!  My only "improvement" would be to perhaps run the build
test immediately after a commit (perhaps only email the author or a
selected list of folks?) if that is feasible.  Folks should be
checking the build before committing (I guess that cannot be the case
with the online editor), but immediately after is the next best thing.

>
> Yannick added code to do this within web/doc-editor/, and it would happen via 
> cron on the editor box (pb11.php.net).
>
> Regards,
> Philip
>
>

Re: [PHP-DOC] How to document 'not implemented, sorta' stuff?

[Peter Cowburn]

On 9 June 2010 16:28, Hannes Magnusson  wrote:
> On Mon, Jun 7, 2010 at 18:56, Philip Olson  wrote:
>>
>> On Jun 7, 2010, at 8:11 AM, G. T. Stresen-Reuter wrote:
>>
>>> On Jun 7, 2010, at 3:47 PM, Philip Olson wrote:
>>>

 There are several features in PHP that are "not implemented [yet]", 
 including roughly 13 DOM classes. Well, they are sorta (but not really) 
 implemented.

 How should we deal with this?
>>>
>>> Just my 2¢ but if something is not (yet) implemented, it doesn't exist and 
>>> thus shouldn't be referenced in any end-user documentation.
>>>
>>> I could never tell my clients about x functionality unless it is, well, 
>>> functional! Doing otherwise could be interpreted as being less than honest.
>>
>> I mostly agree but the trouble is (as seen in the examples) this stuff is 
>> partially implemented. So in the least we should mention them as reserved 
>> keywords (at least, the new classes/methods). Or mention them in better 
>> detail somewhere, and offer alternatives (and/or allow users to provide them 
>> via user comments).
>>
>> I'm not sure the best approach to handling these concerns but am afraid 
>> people think "Oh, this is defined so  probably just isn't documented yet." 
>> which leads them down a time wasting confusing path of testing them out. We 
>> could prevent that, somehow.
>>
>> And in the future I don't think "not implemented yet" should be allowed in 
>> php-src.
>
> IMO it shouldn't and should be removed.

+1

>
> -Hannes
>

[PHP-DOC] Re: [PHP-DEV] Interface and abstract method

[Peter Cowburn]

On 19 May 2010 13:31, Richard Quadling  wrote:
> On 19 May 2010 13:27, mathieu.suen  wrote:
>> Ok so there is no real meaning behind the "abstract".
>> Thanks
>>
>> On 05/18/2010 05:55 PM, Tjerk Anne Meesters wrote:
>>>
>>> Normally, PHP won't allow access types for interface methods, but the
>>> reflection for SPL is defined inside the C code:
>>>
>>> static const zend_function_entry spl_funcs_OuterIterator[] = {
>>>         SPL_ABSTRACT_ME(OuterIterator, getInnerIterator,
>>> arginfo_recursive_it_void)
>>>         {NULL, NULL, NULL}
>>> };
>>>
>>> IMO the SPL_ME should be used instead, but I wouldn't be bothered about it
>>> ;-)

For what it's worth, the non-SPL interfaces use ZEND_ABSTRACT_ME or
similar as far as I can tell. Also, reflection says that all of the
interface methods are abstract (which they are, in the sense of not
having any method body).

>>>
>>> On Tue, May 18, 2010 at 11:12 PM, mathieu.suen
>>>   wrote:
>>>

 Hi,

 In the SPL there is some interface that have abstract method:

 *Countable* {
 /* Methods */
 abstract public int
 count
 ( void )
 }

 While some interface have "none abstract" method.

 *OuterIterator* extends Iterator
   {
 /* Methods */
 public Iterator getInnerIterator
   ( void )
 ..snip..
 }

 Does  "abstract" keyword have a semantic?

 Thanks

 --Mathieu suen





>>>
>>>
>>>
>>
>> -- Mathieu Suen
>>
>>
>>
>>
>
> Seemingly not when it applies to an interface.
>

I think the key issue is that _in the docs_ some interface methods are
marked up as abstract, yet others aren't.  I suggest making them
consistent, having them all being one or t'other.

> --
> -
> Richard Quadling
> "Standing on the shoulders of some very clever giants!"
> EE : http://www.experts-exchange.com/M_248814.html
> EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp
> Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
> ZOPA : http://uk.zopa.com/member/RQuadling
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

Re: [PHP-DOC] What is the use of the $replacement property in the RegexIterator class.

[Peter Cowburn]

On 11 May 2010 13:33:46 UTC+1, Richard Quadling
 wrote:
> On 6 May 2010 08:55, Peter Cowburn  wrote:
>> On 5 May 2010 17:25, Richard Quadling  wrote:
>>> Hi.
>>>
>>> I'm in the process of getting the PHPDoc classes showing the correct
>>> inherited properties and methods (public/protected but not private).
>>>
>>> I picked RecursiveRegexIterator (it has the largest number of
>>> xi:includes in the documentation) as a test.
>>>
>>> Using php --rc I see that the inheritance chain is
>>> RecursiveRegexIterator, RegexIterator, FilterIterator and
>>> IteratorIterator.
>>>
>>> The property $replacement is part of RegexIterator.
>>>
>>> I can see no documentation for this in phpdoc, nor in the Doxygen at
>>> http://www.php.net/~helly/php/ext/spl/
>>>
>>>
>>> In all the examples I've made so far, var_dump()-ing the RegexIterator
>>> results in a ["replacement"]=>NULL
>>>
>>> Assigning a value to $replacement seems to have no bearing on the output.
>>
>> I believe the intention was to give that property a value which could
>> be used with RegexIterator::REPLACE mode but that particular mode has
>> not yet been fully implemented.  There is a related bug (
>> http://bugs.php.net/50579 ) that has not been assigned; I can't say
>> what the plan is for if/when the replacement mode will get some
>> attention. See also: the PHP implementation of RegexIterator (
>> http://svn.php.net/viewvc/php/php-src/trunk/ext/spl/internal/regexiterator.inc?view=markup
>> ).
>>
>>>
>>> Regards,
>>>
>>> Richard.
>>>
>>>
>>> --
>>> -
>>> Richard Quadling
>>> "Standing on the shoulders of some very clever giants!"
>>> EE : http://www.experts-exchange.com/M_248814.html
>>> EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp
>>> Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
>>> ZOPA : http://uk.zopa.com/member/RQuadling
>>>
>>
>
> So, this should be documented as what?
>
> As we don't document the future, I think this property should be
> omitted from the RegexIterator documentation until such time the
> property is useful.
>
> Basically, leave it as is.

Sounds fine to me.

>
> Yes?
>
> --
> -
> Richard Quadling
> "Standing on the shoulders of some very clever giants!"
> EE : http://www.experts-exchange.com/M_248814.html
> EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp
> Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
> ZOPA : http://uk.zopa.com/member/RQuadling
>

Re: [PHP-DOC] What is the use of the $replacement property in the RegexIterator class.

[Peter Cowburn]

On 5 May 2010 17:25, Richard Quadling  wrote:
> Hi.
>
> I'm in the process of getting the PHPDoc classes showing the correct
> inherited properties and methods (public/protected but not private).
>
> I picked RecursiveRegexIterator (it has the largest number of
> xi:includes in the documentation) as a test.
>
> Using php --rc I see that the inheritance chain is
> RecursiveRegexIterator, RegexIterator, FilterIterator and
> IteratorIterator.
>
> The property $replacement is part of RegexIterator.
>
> I can see no documentation for this in phpdoc, nor in the Doxygen at
> http://www.php.net/~helly/php/ext/spl/
>
>
> In all the examples I've made so far, var_dump()-ing the RegexIterator
> results in a ["replacement"]=>NULL
>
> Assigning a value to $replacement seems to have no bearing on the output.

I believe the intention was to give that property a value which could
be used with RegexIterator::REPLACE mode but that particular mode has
not yet been fully implemented.  There is a related bug (
http://bugs.php.net/50579 ) that has not been assigned; I can't say
what the plan is for if/when the replacement mode will get some
attention. See also: the PHP implementation of RegexIterator (
http://svn.php.net/viewvc/php/php-src/trunk/ext/spl/internal/regexiterator.inc?view=markup
).

>
> Regards,
>
> Richard.
>
>
> --
> -
> Richard Quadling
> "Standing on the shoulders of some very clever giants!"
> EE : http://www.experts-exchange.com/M_248814.html
> EE4Free : http://www.experts-exchange.com/becomeAnExpert.jsp
> Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
> ZOPA : http://uk.zopa.com/member/RQuadling
>

Re: [PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/en/trunk/reference/datetime/datetime/ add.xml modify.xml setdate.xml setisodate.xml settime.xml settimestamp.xml settimezone.xml sub.xml

[Peter Cowburn]

On 4 May 2010 22:03, Daniel Convissor  wrote:
> Hi Derick:
>
> On Tue, May 04, 2010 at 06:12:25PM +0100, Derick Rethans wrote:
>>
>> There is still a difference in userland between:
>>
>> function tralala ( $foo );
>>
>> and
>>
>> function tralala ( &$foo );
>>
>> with $foo being fed an object. Objects are passed by a handle, so it
>> looks like a reference.
>
> Yep.  Though this documentation isn't covering userland.
>
>
>> AFAIK the refence bit is not used there in the XML.
>
> It is used, turning the output from $var to &$var.
>
> So would you and the doc team rather I explain in the parameters section
> that the $object parameter gets modified by the operation?  Is there a
> particular term for this?

"Expected behaviour" ??

>
> --Dan
>
> --
>  T H E   A N A L Y S I S   A N D   S O L U T I O N S   C O M P A N Y
>            data intensive web and database programming
>                http://www.AnalysisAndSolutions.com/
>  4015 7th Ave #4, Brooklyn NY 11232  v: 718-854-0335 f: 718-854-0409
>

Re: [PHP-DOC] SVN Account Request: dtajchreber

[Peter Cowburn]

On 1 May 2010 19:21, Philip Olson  wrote:
>
> On May 1, 2010, at 10:55 AM, David Tajchreber wrote:
>
>> Bug fixes in the doc, phd, and web.
>
> Hello David,
>
> As you've (under the alias Yawk) already hung around IRC for many months and 
> submitted several patches and suggestions, it feels like you've already been 
> part of the team ;) But now this account has been approved with karma 
> granted, welcome to the PHP documentation team!

Finally! Welcome aboard. :)

>
> Regards,
> Philip
>
>

Re: [PHP-DOC] listing inherited properties

[Peter Cowburn]

On 29 April 2010 08:18, Philip Olson  wrote:
>
> Moments ago Yawk asked in IRC about why we list inherited methods but not 
> inherited properties. Good question. So unless someone comes up with a 
> reason, let's add them too. Okay? It can use the same form of xpointer inside 
> the classname.xml files.

Good call, thanks yawk! I've had a number of folks in the past ask my
about why a certain class constant is available but not in the docs so
it would be good to have them listed in the class synopsis.

While we're on the topic, if anyone is looking to go through some
classes to add in these inherited constants then it would be worth
checking for inherited methods as well since not all classes have them
listed.

>
> Regards,
> Philip
>
>

Re: [PHP-DOC] improving object oriented / procedural combinations

[Peter Cowburn]

On 22 April 2010 03:28, Daniel Convissor
 wrote:
> Hi Folks:
>
> In trying to add the procedural style interface to the DateTime docs I
> went searching for how we currently present stuff that has both object
> oriented and procedural interfaces.  It turns out there is no consistent
> way of going about it, plus there are some other oddities that would be
> good to discuss.
>
> 1) How to label the OOP methodsynopsis?
>
> Here are the current usages:
>
> Object oriented style:
> Object oriented style
> Object oriented style (method):
> Object oriented style (method)
> Object oriented style (constructor):
> Object oriented style (property):
> Object oriented style (property)
> &style.oop;
>
> (Though the style.oop entity was mistakenly defined as "Oriented object
> style", though I just fixed it to "Object oriented style".
>
> I suggest we go with &style.oop; (mapping to "Object oriented style") for
> everything.  The parenthetical method/constructor/property are
> supurfluous because the way the stuff is rendered clearly explains the
> usage.
>
> Similarly, "&style.procedural;" should be substituted for "Procedural
> style".
>
> Does this seem reasonable to you?

Yes, using just the entities wherever possible seems the best approach to me.

>
>
> 2) Where to put the example output?
>
> Generally, output for examples is put inside the  element.  But
> when both OOP and procedural styles are shown, it's easier to
> write/maintain one output.
>
> Some docs put it in one of the examples, a la
> http://us3.php.net/manual/en/rararchive.getcomment.php.  It's a somewhat
> inelegant.
>
> Some docs put it outside the  section.  It works, but it looks a
> little funny without it being offset inside a box.  See
> http://us3.php.net/manual/en/mysqli.affected-rows.php for what I mean.
>
> I did a test of putting the output block inside a separate 
> element just above .  It works nicely.  Does this sound good
> to everyone?

I don't think having a new example block just for output makes much
semantic sense. How about having multiple  elements
(one per paradigm) and one  with the &examples.outputs*
entities?

>
>
> 3) The way properties are documented/rendered in description refsect1's
> can be better.
>
> Take a look at mysqli affected-rows page (same as above link).  "mysqli"
> is in a box on one line and then "int $affected_rows;" is on another row.
> Right now we mark up the DocBook like this:
>
>  
>   mysqli
>   
>    intaffected_rows
>   
>  
>
> The  / class name in this section of the output is
> unnecessary because the class in question is clear from the page
> title/etc, plus we don't use it for methods.
>
> It seems like things would be much clearer if the class name weren't
> there and it came out something like this:
>
>  public int $affected_rows
>
> DocBook allows the  to go directly into the .
> So to accomplish this, the DocBook can be written as such:
>
>  
>   public
>   int
>   affected_rows
>  
>
> and then add "div.refsect1 div.fieldsynopsis" to line 979 of site.css to
> get the border around it just like "div.refsect1 div.methodsynopsis".
> Looks sweet.  What do people think?
>
>
> Once we come to agreements on which ways to go, I'll be glad implement
> them throughout the existing files.
>
> Thanks,
>
> --Dan
>
> --
>  T H E   A N A L Y S I S   A N D   S O L U T I O N S   C O M P A N Y
>            data intensive web and database programming
>                http://www.AnalysisAndSolutions.com/
>  4015 7th Ave #4, Brooklyn NY 11232  v: 718-854-0335 f: 718-854-0409
>

Re: [PHP-DOC] Subversion access to contribute documentation fixes

[Peter Cowburn]

On 20 April 2010 23:11, Patrick van Staveren  wrote:
> Hello,

Hi Patrick!

>
> I'd like to contribute to the PHP manual.

Excellent, the more the merrier!

> I'd like a subversion account if
> someone will give me karma.  If not I'll just send patches here :)

The general procedure is to introduce yourself to the list (done) and
fire off a few patches and see if you've got the hang of things, or to
ask/answer questions to guide you along and then, if all is well and
you haven't been scared off, that's when we give you some commit
karma.  So, if you don't mind, could you send those patches to the
list for us to take a gander over and we can move from there?

>
> I've been developing PHP applications for many years, and manage a team of
> developers who use PHP daily.  The manual is critical to our success, and
> I'm also a stickler for good documentation.  Every now and then I run across
> things that could do with a better explanation or aren't documented
> thoroughly enough and I'd like to help when I can.
>
> I set up a build of the manual today, learned a bit of docbook and made two
> patches to the curl_setopt page, so I'm ready to go!  (As a result I'd like
> to update the page "The quicky",
> http://doc.php.net/php/dochowto/article.thequicky.exceptions.php , which
> contains a small mistake.)

Looks like you're off to a flying start. As I said above, if we could
see those patches that would be great. Also if you have any quicky
questions that you mightn't want to bother the list with then do join
us on IRC if you haven't already: irc.efnet.org#php.doc

>
> Cheers,
> Patrick van Staveren
> http://trick.vanstaveren.us/
>
>
>

Re: [PHP-DOC] user notes: code snippets

[Peter Cowburn]

On 8 April 2010 20:29, Philip Olson  wrote:
>
> A few thoughts that come to mind:
>  * Tagged as a code snippet

I'm against the idea of tagging user-contributed notes, whatever type
they are. This isn't the place however to ramble on that particular
topic sufficing to say I don't want it for snippets or anything else.

>  * Users rate it, 1-10

If this was amended to an up/down rating it would get my (up) vote,
pending seeing it in action.  Rated notes could help sort the wheat
from the chaff in a way that chronological ordering just cannot do.

>  * Ensure the copyright/license stuff is clear

Currently the only mention* of this sort of thing on the add-note page
is in relation to letting us merge comments into the documentation
proper.  (* After a very cursory glance around!)

>  * Dealing with PHP version requirements?

I would expect many of the people contributing code snippets not to
know the precise versions under which their snippet should be labelled
and looking up those requirements for anything more than a simple
function call, or at all, might be asking too much.  Assuming comments
on notes are allowed, someone in-the-know could clarify the versions
if folks are having trouble.

>  * Users comment on individual snippets?

Yes please.

>  * Some notes will contain a lot of words with a small code snippet, what tag 
> is it?

Waffle. :-)

> Example of good versus bad:
>  * A piece of code is well written, about 20 lines, and is about creating a 
> password. It happens to use strlen() a couple times so is posted under 
> function.strlen. Good? Bad?

Bad. I think the notes should be relevant to the manual page under
which they're posted. The code should be demonstrating the use of
strlen rather than demonstrating how to create a password—where would
the latter go? Perhaps there will not be a clear distinction but to
give a more crude example, I don't think any snippet using the
concatenation operator should go under the string operators manual
page!

>
> A few other questions:
>  * Let's say a piece of code is great, voted up, and uses 5 internal PHP 
> functions. Should we scan it, then automagically make the snippet linked to 
> the 5 manual pages?

No. See my previous comment. I'd rather let the author decide (with
some moderation of course) where their contribution lives.

>  * We don't plan on becoming a full blown code repository, or do we? Worth 
> worrying about?

I think it is worth worrying about; with all this discussion I fear
we're going to be placing more community-emphasis on the user notes,
snippets, comments-on-notes-and-snippets, etc. than on (improving) the
documentation itself. That might be a good thing (community
involvement always is) or bad (it is *the manual*, after all).

>  * Should we suggest (not enforce) coding standards?

Sure. If we're going after the copy-and-paste crowd then the code
might as well be at least a little bit consistent. Whether people
would follow whatever standards are suggested would be another matter
entirely.

>
> And lastly, one problem about coding examples is how good practice can dilute 
> the example. So for example, while teaching people about $_GET['foo'] we may 
> end up with one of:
>  A) echo htmlspecialchars($_GET['foo'], ENT_QUOTES, 'UTF-8'); // Hello World
>  B) echo $_GET['foo']; // Hello World
>
> The (A) dilutes the idea of $_GET whereas (B) is clear. So which is the 
> better example? Probably (A) in this case but the point is it's not 
> straightforward.

Both snippets are demonstrating different ideas (escaping output
versus a simple example of using $_GET). It would help if when adding
snippets, the reason for/behind it is made clear: am I just posting a
super-simple example without caring for best practices or do I just
not know better?

Re: [PHP-DOC] What to do with PHP 6

[Peter Cowburn]

On 31 March 2010 15:25, Christopher Jones  wrote:
>
>
> On 03/31/2010 03:13 AM, Robert P. J. Day wrote:
>>
>> On Tue, 30 Mar 2010, Philip Olson wrote:
>>
>>> Hello everyone,
>>>
>>> As most of us know, PHP 6 has disappeared. It used to be 5.3+unicode
>>> but now it's unknown and certainly not worth mentioning in the PHP
>>> manual (at least, as a version that introduces features/changes).
>>> With that said, let's talk about what to do. First:
>>>
>>>  $ egrep --exclude=\*.svn\* -r -n "PHP 6" * |wc -l
>>>  >  105
>>>
>>> Or, better than grep ;)
>>>
>>>  $ ack "PHP 6" * |wc -l
>>>  >  105
>>>
>>> Around 13 are in versions.xml, and 51 in ini.xml. We must handle this as
>>> a case-by-basis because not all of these features are unicode specific, and
>>> even those that are may [or may not] be in the next PHP version for all we
>>> know... nobody really knows. Our options:
>>>
>>>  (a) Remove or comment out the docs (a sad thought)
>>>  (b) Make guesses as to which PHP version they'll be in (5.4 is likely
>>> for many, but easily wrong)
>>>  (c) Move them to an appendix (doesn't feel right)
>>>  (d) Write "Future PHP Release" or similar until we know (seems okay)
>>>  (e) ...
>>>
>>> I lean towards (d) for most cases. Thoughts?
>>
>>   call it "PHP NG", with a huge early disclaimer that you're not sure
>> what the number will be.
>
> It's not clear if/how these features are going to be re-included.
>
> I'd prefer to see them commented out.  Displaying mis-information is
> harmful to the overall PHP project.

I'm on this side of the fence. I think our main role is to document
things as they are now.  For those things that were in trunk but no
longer exist I vote for removing them (commenting out) until such a
point when (if) they get pushed back into the code.  As for how we
label additions which will be released at some point but for which the
version number(s) are not certain, that's a puzzle that we must ponder
for a while.

>
> Chris
>
> --
> Email: christopher.jo...@oracle.com
> Tel:  +1 650 506 8630
> Blog:  http://blogs.oracle.com/opal/
> Free PHP Book: http://tinyurl.com/ugpomhome
>

[PHP-DOC] Documenting common methods in SPL

[Peter Cowburn]

Hi folks,

A few of us have been discussing this topic (on IRC) periodically for
a while with a little bit of a TODO on the wiki[1].  This mail is
going out to hopefully reach a wider audience and get some helpful
discussion going (and maybe even some decisions?).

Please take a minute to review the section entitled "Similar methods"
on the wiki page and then, if you have any feedback, reply here.  It
would be nice to get this particular issue (or it may turn into a
non-issue after discussion) sorted so that we can push ahead with the
remaining undocumented portions of the SPL (still roughly a third of
the library).

[1] http://wiki.php.net/doc/todo/spldocs

Re: [PHP-DOC] SPL Autoload Register Patch

[Peter Cowburn]

2009/7/28 Brandon Savage :
>
> On Jul 28, 2009, at 4:17 AM, Hannes Magnusson wrote:
>
>> On Tue, Jul 28, 2009 at 01:30, Brandon Savage
>> wrote:
>>>
>>> I spent a bit going over the wording with someone else before I submitted
>>> it. According to what I understand, it creates a stack, but doesn't
>>> behave
>>> in the way a stack does (last in first out). Effectively it's a queue but
>>> I
>>> believe it places the functions on the stack, so I'm not really sure. I
>>> do
>>> know it goes through then in a first-in, first-out sort of fashion.
>>>
>>> I don't see the WS you're referring to.
>>
>>
>> Me neither.
>>

I can see a single space between  and spl_autoload_register
on line 10 of the latest patch in this thread (dated 27 July 2009
12:48 for me), it is that to which I was referring. Like you, I've no
idea if whitespace within tags like  is significant or not.

>> Are you planning on contributing more docs, or do you want someone to
>> commit this for you?
>>
>> I was told on IRC that my replies looked "brutal", which was totally
>> not the intention.
>> I thought you were posting so small patch just to get hang of these
>> things and looking for all possible feedback to "get it right" before
>> looking at bigger tasks..
>>
>> I could easily have adjusted your initial patch myself and committed
>> it right away if you had no interest in contributing more and didn't
>> want to learn how to do it better.
>>
>> -Hannes
>
> I've been on the list a while, but I was asked to modify the docs in this
> case. It's fairly straight forward so I will probably edit them as an
> ongoing process, and learning how it's done.
>

Re: [PHP-DOC] SPL Autoload Register Patch

[Peter Cowburn]

2009/7/27 Peter Cowburn :
> 2009/7/27 Brandon Savage :
>>
>>
>> On Mon, Jul 27, 2009 at 7:43 AM, Hannes Magnusson
>>  wrote:
>>>
>>> On Mon, Jul 27, 2009 at 13:36, Brandon Savage
>>> wrote:
>>> >
>>> >
>>> > On Mon, Jul 27, 2009 at 7:28 AM, Hannes Magnusson
>>> >  wrote:
>>> >>
>>> >> Don't top-post.
>>> >>
>>> >> On Mon, Jul 27, 2009 at 13:24, Brandon
>>> >> Savage
>>> >> wrote:
>>> >> >
>>> >> > On Mon, Jul 27, 2009 at 7:21 AM, Hannes Magnusson
>>> >> >  wrote:
>>> >> >>
>>> >> >> Don't top-post :)
>>> >> >>
>>> >> >> On Mon, Jul 27, 2009 at 13:14, Brandon
>>> >> >> Savage
>>> >> >> wrote:
>>> >> >> >
>>> >> >> > On Mon, Jul 27, 2009 at 3:39 AM, Hannes Magnusson
>>> >> >> >  wrote:
>>> >> >> >>
>>> >> >> >> On Sat, Jul 25, 2009 at 18:59, Brandon
>>> >> >> >> Savage
>>> >> >> >> wrote:
>>> >> >> >> > This is my first time submitting a patch, but I was asked to
>>> >> >> >> > add
>>> >> >> >> > to
>>> >> >> >> > the
>>> >> >> >> > documentation and so here goes.
>>> >> >> >> >
>>> >> >> >> > Please let me know if I did anything incorrectly.
>>> >> >> >>
>>> >> >> >> We try to stay away from "you this" and "you that".. The
>>> >> >> >> documentations should be using 3rd person :]
>>> >> >> >>
>>> >> >> > I fixed those issues. Let me know if there are any others.
>>> >> >> >
>>> >> >>
>>> >> >> Function names should be wrapped in  elements, i.e.
>>> >> >> "spl_autoload_register allows.."
>>> >> >>
>>> >> > Done.
>>> >> >
>>> >> > Can we make a comprehensive list of anything else that's wrong so we
>>> >> > can
>>> >> > avoid the back-and-forth?
>>> >> >
>>> >>
>>> >> () should not be used with . The  element
>>> >> automatically generates those.
>>> >>  is also missing around __autoload.
>>> >> Lines should preferably not be longer then 80chars.
>>> >>
>>> >> Can't think of anything else.
>>> >>
>>> >
>>> > Alright. Characters limited to 80, and () removed.
>>> >
>>>
>>> I'm unsure how the WS between  and the actual content of it
>>> will be handled, it will probably be trimmed away.. but it'll make
>>> grepping for spl_autoload_register a total
>>> nightmare.
>>> I'd recommend either break the 80chars limit "rule" or move 
>>> down to the new line too.
>>>
>>> -Hannes
>>
>> I was concerned about that but I wasn't sure whether the 80-char rule was
>> hard or soft.
>>
>> I moved it up and broke the rule, but that should make grepping easier (and
>> keep us from finding out how WS affects it).
>>
>>
>
> There is still whitespace to the left of the function name inside the
>  tags. Also, I'm not particularly keen on the way this is
> worded. The whole "If there must be..." sentence feels clunky and
> gives a feeling of "we'd prefer it if you didn't, but..." which I'm
> sure is not intentional.  I'd prefer to be more concise with something
> like "spl_autoload_register allows multiple
> autoload handlers to be registered" (I used "handlers" simply because
> methods can be used, not just functions).
>
> Does it "effectively" create a queue, or actually do so? Finally, does
> spl_autoload_register run through the registered autoloaders in the
> order in which they're defined, or the order in which they are
> registered?
>
> Sorry for being particularly picky over a single paragraph!!
>

The previous reply probably came off _much_ more demanding than it
really should be. What you wrote is perfectly acceptable. My reply was
simply how I (just me, nothing official) might've approached it
differently; different doesn't equate to right or wrong! I'm still
very new to the documentation team myself so please don't take my word
as anything authoritative. In the end, it's a helpful paragraph
detailing what needs to be detailed.

Also, thanks for taking the step up to documenting. If you haven't
already, two good pages on conventions/style can be found at
http://doc.php.net/php/dochowto/chapter-conventions.php which is part
of the bigger "how to" section on documenting and
http://wiki.php.net/doc/articles/nomenclature for grammatical details.

Re: [PHP-DOC] SPL Autoload Register Patch

[Peter Cowburn]

2009/7/27 Brandon Savage :
>
>
> On Mon, Jul 27, 2009 at 7:43 AM, Hannes Magnusson
>  wrote:
>>
>> On Mon, Jul 27, 2009 at 13:36, Brandon Savage
>> wrote:
>> >
>> >
>> > On Mon, Jul 27, 2009 at 7:28 AM, Hannes Magnusson
>> >  wrote:
>> >>
>> >> Don't top-post.
>> >>
>> >> On Mon, Jul 27, 2009 at 13:24, Brandon
>> >> Savage
>> >> wrote:
>> >> >
>> >> > On Mon, Jul 27, 2009 at 7:21 AM, Hannes Magnusson
>> >> >  wrote:
>> >> >>
>> >> >> Don't top-post :)
>> >> >>
>> >> >> On Mon, Jul 27, 2009 at 13:14, Brandon
>> >> >> Savage
>> >> >> wrote:
>> >> >> >
>> >> >> > On Mon, Jul 27, 2009 at 3:39 AM, Hannes Magnusson
>> >> >> >  wrote:
>> >> >> >>
>> >> >> >> On Sat, Jul 25, 2009 at 18:59, Brandon
>> >> >> >> Savage
>> >> >> >> wrote:
>> >> >> >> > This is my first time submitting a patch, but I was asked to
>> >> >> >> > add
>> >> >> >> > to
>> >> >> >> > the
>> >> >> >> > documentation and so here goes.
>> >> >> >> >
>> >> >> >> > Please let me know if I did anything incorrectly.
>> >> >> >>
>> >> >> >> We try to stay away from "you this" and "you that".. The
>> >> >> >> documentations should be using 3rd person :]
>> >> >> >>
>> >> >> > I fixed those issues. Let me know if there are any others.
>> >> >> >
>> >> >>
>> >> >> Function names should be wrapped in  elements, i.e.
>> >> >> "spl_autoload_register allows.."
>> >> >>
>> >> > Done.
>> >> >
>> >> > Can we make a comprehensive list of anything else that's wrong so we
>> >> > can
>> >> > avoid the back-and-forth?
>> >> >
>> >>
>> >> () should not be used with . The  element
>> >> automatically generates those.
>> >>  is also missing around __autoload.
>> >> Lines should preferably not be longer then 80chars.
>> >>
>> >> Can't think of anything else.
>> >>
>> >
>> > Alright. Characters limited to 80, and () removed.
>> >
>>
>> I'm unsure how the WS between  and the actual content of it
>> will be handled, it will probably be trimmed away.. but it'll make
>> grepping for spl_autoload_register a total
>> nightmare.
>> I'd recommend either break the 80chars limit "rule" or move 
>> down to the new line too.
>>
>> -Hannes
>
> I was concerned about that but I wasn't sure whether the 80-char rule was
> hard or soft.
>
> I moved it up and broke the rule, but that should make grepping easier (and
> keep us from finding out how WS affects it).
>
>

There is still whitespace to the left of the function name inside the
 tags. Also, I'm not particularly keen on the way this is
worded. The whole "If there must be..." sentence feels clunky and
gives a feeling of "we'd prefer it if you didn't, but..." which I'm
sure is not intentional.  I'd prefer to be more concise with something
like "spl_autoload_register allows multiple
autoload handlers to be registered" (I used "handlers" simply because
methods can be used, not just functions).

Does it "effectively" create a queue, or actually do so? Finally, does
spl_autoload_register run through the registered autoloaders in the
order in which they're defined, or the order in which they are
registered?

Sorry for being particularly picky over a single paragraph!!

Re: [PHP-DOC] [HEADSUP] Call for help

[Peter Cowburn]

> 2009/7/5 Daniel Brown :
> Still, there are a couple of minor changes
> and some typofixes herein.

I also made a few, very minor changes in an effort to make sentences
flow a little better (for me at least) and to fix an existing typo
("explaination").

> My only real question is if we want to
> leave the "kick-ass" portion in there, since it's going on the main
> page, or if we'd want to approach it with a slightly more professional
> tenor.  I don't think it's inappropriate to a level of being obscene,
> but maybe a bit abrasive.

For what it's worth, I'd rather see "kick-ass awesome" in there than
it being left out. :)

>    Regardless, the new XML is attached.

Ditto.

http://www.w3.org/2005/Atom";>
  Thin documentation?
  http://www.php.net/archive/2009.php#id2009-07-05-1
  2009-07-05T01:40:12+02:00
  2009-07-05T01:40:12+02:00
  
  http://www.php.net/index.php#id2009-07-05-1"; rel="alternate" type="text/html"/>
  http://www.php.net/archive/2009.php#id2009-07-05-1"; rel="via" type="text/html"/>
  
http://www.w3.org/1999/xhtml";>
 Since the inception of PHP it has been known for having _the_ best, kick-ass awesome documentation.
 In recent years, some have commented on the fact that the documentation of new features is insufficient, and lacks in-detail explanations and descriptions of common "what-if" scenarios.
 Effective immediately, we are placing an open call for volunteers to help the project to get up to speed with the massive changes PHP has undergone in recent years, and to catch up with all the new features the language has to offer.
 Obviously any and all contributions to the project are very much appreciated and getting a CVS account along with the appropriate karma is a very simple task.
 If you are interested in helping out, please contact the documentation team at phpdoc@lists.php.net today.

  

Re: [PHP-DOC] Re: [DOC-CVS] cvs: phpdoc /en/appendices migration53.xml

[Peter Cowburn]

>
> Would it not be 41-byte (like 10-month-old baby or 5-day work week?

I would go with this suggestion to make a compound adjective (iirc). I
am not sure if there is some preference towards hyphenating in British
English compared to American English, or vice versa, but I would
hyphenate most of the examples given in this discussion thread! Either
way, with or without hyphen, the "bytes" should definitely be
singular.

> I do not know the absolute grammar rule that covers this, but it seems to me
> that the parts should be joined with a hyphen because they act as a single
> adjective.
>
> -Garrett
>

[PHP-DOC] CVS Account Request: salathe

[Peter Cowburn]

Adding, or amending, the documentation.

[PHP-DOC] First attempt at contributing (SPL DirectoryIterator)

[Peter Cowburn]

Hi folks,

This is my first attempt at contributing any documentation so things
*may* not be as you want them; I've done my best by reading the
literature available on producing docs and the changes appear to build
happily with phd.  I'll attach a link to the diffs/new files as there
are quite a lot.  Also, would a contributor be expected to edit things
like entities/file-entities.ent or other entities files (eg
en/reference/spl/entities.directoryiterator.xml) for new files added—I
haven't attached changes to any entity files because of not know what
needed to be done.

So, the additions/changes are available at
https://gist.github.com/b7c0c2c8379c7c6679c6

If anyone wants to discuss off-list (to help a new contributor out,
maybe?) I try to pop in to IRC (nick, salathe). If all goes well, I'd
like to continue with SPL-file-related docs.

Regards,
Peter

Re: [PHP-DOC] spl update: methods missing = 182 and undocumented = 62

[Peter Cowburn]

Hi everyone, first message to this mailing list!

Just a note that I'm currently looking over the DirectoryIterator and
SplFileInfo classes.

Regards,
Peter

On Tue, Apr 28, 2009 at 10:42 PM, Philip Olson  wrote:
> Hello geeks,
>
> Here's another SPL documentation progress report. Juliette is working on the
> ArrayObject documentation, whereas the rest is considered open.
>
> Regards,
> Philip
>
> Generated by: phpdoc/scripts/check-missing-spldocs.php
>
> Missing files:
> Array
> (
>    [0] => appenditerator/append.xml
>    [1] => appenditerator/construct.xml
>    [2] => appenditerator/current.xml
>    [3] => appenditerator/getarrayiterator.xml
>    [4] => appenditerator/getinneriterator.xml
>    [5] => appenditerator/getiteratorindex.xml
>    [6] => appenditerator/key.xml
>    [7] => appenditerator/next.xml
>    [8] => appenditerator/rewind.xml
>    [9] => appenditerator/valid.xml
>    [10] => appenditerator.xml
>    [11] => arrayiterator/append.xml
>    [12] => arrayiterator/asort.xml
>    [13] => arrayiterator/construct.xml
>    [14] => arrayiterator/count.xml
>    [15] => arrayiterator/getarraycopy.xml
>    [16] => arrayiterator/getflags.xml
>    [17] => arrayiterator/ksort.xml
>    [18] => arrayiterator/natcasesort.xml
>    [19] => arrayiterator/natsort.xml
>    [20] => arrayiterator/offsetexists.xml
>    [21] => arrayiterator/offsetget.xml
>    [22] => arrayiterator/offsetset.xml
>    [23] => arrayiterator/offsetunset.xml
>    [24] => arrayiterator/serialize.xml
>    [25] => arrayiterator/setflags.xml
>    [26] => arrayiterator/uasort.xml
>    [27] => arrayiterator/uksort.xml
>    [28] => arrayiterator/unserialize.xml
>    [29] => arrayobject/asort.xml
>    [30] => arrayobject/exchangearray.xml
>    [31] => arrayobject/getarraycopy.xml
>    [32] => arrayobject/getflags.xml
>    [33] => arrayobject/getiteratorclass.xml
>    [34] => arrayobject/ksort.xml
>    [35] => arrayobject/natcasesort.xml
>    [36] => arrayobject/natsort.xml
>    [37] => arrayobject/serialize.xml
>    [38] => arrayobject/setflags.xml
>    [39] => arrayobject/setiteratorclass.xml
>    [40] => arrayobject/uasort.xml
>    [41] => arrayobject/uksort.xml
>    [42] => arrayobject/unserialize.xml
>    [43] => directoryiterator/getbasename.xml
>    [44] => directoryiterator/seek.xml
>    [45] => directoryiterator/tostring.xml
>    [46] => emptyiterator/current.xml
>    [47] => emptyiterator/key.xml
>    [48] => emptyiterator/next.xml
>    [49] => emptyiterator/rewind.xml
>    [50] => emptyiterator/valid.xml
>    [51] => emptyiterator.xml
>    [52] => filteriterator/accept.xml
>    [53] => filteriterator/construct.xml
>    [54] => infiniteiterator/construct.xml
>    [55] => infiniteiterator/next.xml
>    [56] => infiniteiterator.xml
>    [57] => limititerator/construct.xml
>    [58] => limititerator/current.xml
>    [59] => limititerator/getinneriterator.xml
>    [60] => limititerator/key.xml
>    [61] => multipleiterator/attachiterator.xml
>    [62] => multipleiterator/construct.xml
>    [63] => multipleiterator/containsiterator.xml
>    [64] => multipleiterator/countiterators.xml
>    [65] => multipleiterator/current.xml
>    [66] => multipleiterator/detachiterator.xml
>    [67] => multipleiterator/getflags.xml
>    [68] => multipleiterator/key.xml
>    [69] => multipleiterator/next.xml
>    [70] => multipleiterator/rewind.xml
>    [71] => multipleiterator/setflags.xml
>    [72] => multipleiterator/valid.xml
>    [73] => multipleiterator.xml
>    [74] => norewinditerator/construct.xml
>    [75] => norewinditerator/current.xml
>    [76] => norewinditerator/getinneriterator.xml
>    [77] => norewinditerator/key.xml
>    [78] => norewinditerator/next.xml
>    [79] => norewinditerator/rewind.xml
>    [80] => norewinditerator/valid.xml
>    [81] => norewinditerator.xml
>    [82] => outeriterator/getinneriterator.xml
>    [83] => outeriterator.xml
>    [84] => parentiterator/accept.xml
>    [85] => parentiterator/construct.xml
>    [86] => recursivearrayiterator/getchildren.xml
>    [87] => recursivearrayiterator/haschildren.xml
>    [88] => recursivearrayiterator.xml
>    [89] => recursivecachingiterator/construct.xml
>    [90] => recursivedirectoryiterator/construct.xml
>    [91] => recursivedirectoryiterator/getsubpath.xml
>    [92] => recursivedirectoryiterator/getsubpathname.xml
>    [93] => recursivefilteriterator/construct.xml
>    [94] => recursivefilteriterator/getchildren.xml
>    [95] => recursivefilteriterator/haschildren.xml
>    [96] => recursivefilteriterator.xml
>    [97] => recursiveiterator/getchildren.xml
>    [98] => recursiveiterator/haschildren.xml
>    [99] => recursiveiterator.xml
>    [100] => recursiveiteratoriterator/beginchildren.xml
>    [101] => recursiveiteratoriterator/beginiteration.xml
>    [102] => recursiveiteratoriterator/callgetchildren.xml
>    [103] => recursiveiteratoriterator/callhaschildren.xml
>    [104] => recursiveiteratoriterator/construct.xml
>    [105] => recursiveiteratoriterator/endchildren.x