Note the link in the above bug Description, to my annotation at the flock() manual page, was incorrect and should be:

http://www.php.net/manual/en/function.flock.php#94682

I have summarized the issues there:

* LOCK_NB does work on Windows, only the wouldblock argument is not supported.

* LOCK_NB option may be combined with the other LOCK_* options, which may not be combined with each other.

* May be used with NFS because implementation uses fcntl.

* Locking is mandatory in some cases in addition to Windows.

* OS with Posix.1 compliant fcntl will release all a scripts' flock()s on a file, if that same script fclose() any file handle on that file.

* Do not confuse the LOCK_* values (1,2,3,4) input to this function, with the LOCK_* OS values (1,2,4,8), even though their semantics are similar.

For the record, I rejected your note from the manual page.  It's enough 
to have this bug report in place, and is unnecessary to append a note to 
the page as well.  It just leaves more housekeeping for later.

Dan Brown I had already read the submission guidelines for manual annotations, and in fact my notation repeats some of the other notations already on the manual page (e.g. that LOCK_NB is a binary flag option that can be combined with options).

Removing my note from the manual page, means that others will spend a whole day of frustration trying to figure out what I figured out, for as long as the manual is not fixed, which who knows might be months or even years.

So you preference is to deny the users the information, because they surely won't find this bug report in meantime?

I put a link here in the bug report, so who ever fixes the bug, can send an email to the note editor to remove my note later.

Your premature deletion of my note did not save any housekeeping effort on your part, it merely destroys my work and hides the information from the millions of PHP users.

Shame on you Dan Brown. At least you had the dignity to post here what you had done, so I can reply to you.

Waste my time once, but never again.  I will withhold my contributions from PHP from here out.

Congratulations.

In the meantime, you have many errors in those user comments which did get approved on that page.  Talk about future housekeeping!  Dan you have no point and no logic.  But you are good at destroying effort and chasing away the people who do apply inspired effort.

==
KEY:
> Your Comments
My Responses
==

> Dan Brown I had already read the submission
> guidelines for manual annotations, and in
> fact my notation repeats some of the other
> notations already on the manual page (e.g.
> that LOCK_NB is a binary flag option that
> can be combined with options).
> 
> Removing my note from the manual page,
> means that others will spend a whole
> day of frustration trying to figure
> out what I figured out, for as long as
> the manual is not fixed, which who
> knows might be months or even years.

Not true.  When a documentation bug is
submitted, it is usually resolved within
72 hours.  So until you know for a fact
how the timing and patterns work, either
join the project or don't make assumptions
in how we operate, or question why we do
things the way we do, thanks.


> So you preference is to deny the users
> the information, because they surely
> won't find this bug report in meantime?

My preference is to maintain a good, solid
reliable presentation, and not to confuse
others with conflicting or redundant
information.  When a documentation bug is
fixed, it's not normal procedure to then
sift through every annotation on the
corresponding manual entry to ensure that
we've updated it.  One could only imagine
the effort that would take.  However,
your estimation as to the intelligence of
your peers and their ineptitude at tracking
down relevant information is interesting
to me.  Have you frequently found yourself
in situations where you are the only one
with enough sense to help yourself?  If
you pass judgment as to the ability of
those around you, my guess is that you'd
find yourself quite lonely in many circles.


> I put a link here in the bug report, so
> who ever fixes the bug, can send an email
> to the note editor to remove my note later.

Links don't work that way, Shelby.  They
direct you TO a page, they do not report
back FROM the target.  So this is baseless.


> Your premature deletion of my note did not
> save any housekeeping effort on your part,
> it merely destroys my work and hides the
> information from the millions of PHP users.

It was not premature, and in fact did serve
its purpose in housekeeping.  Further, please
check your metrics, as "millions of PHP users"
would be fantastic, but I think may be a bit
exaggerated in this case.


> Shame on you Dan Brown. At least you
> had the dignity to post here what you
> had done, so I can reply to you.

Dignity is the one thing I didn't have to
sacrifice on my wedding day.  Now, if we
were to discuss other things like personal
space or sanity....


> Waste my time once, but never again.  I
> will withhold my contributions from PHP
> from here out.

It's worth noting that, within a few moments,
you posted a follow-up on this report.  Perhaps
you meant this promise to be appended to the
end of that message.


> Congratulations.

Thank you.  It's been a long, difficult
journey, but we appreciate your support.  We'd
like to thank the Academy....

==
KEY:
> Your Comments
My Responses
==

> In the meantime, you have many errors in
> those user comments which did get approved
> on that page.  Talk about future housekeeping!

Tell me about it!  It's an ongoing effort, and
one in which we'd certainly welcome the
assistance of someone with as much time available
as you're demonstrating in noticing the errors.
We're all volunteers who donate our time to the
community on a daily basis, and if you'd like
to join the ranks to offer your assistance in
making things better for your fellow PHP
developers, it would be greatly appreciated!


> Dan you have no point and no logic.  But you
> are good at destroying effort and chasing
> away the people who do apply inspired effort.

Aww, when you say it, it hurts.

If it is true that documentation errors are resolved within 72 hours, then I eat my words and humbly apologize to you.

If you simply added that statement-of-fact to the policy page and to the rejection email, then I wouldn't have even bothered adding the note to the manual page.

I do not understand why you wouldn't make that clear on the policy, so that people will not feel like they have fallen in a blackhole, as can be the case in other social politics.

Again if that is the case, my apologies.  I was offended, because I have had my effort wasted too many times in past and it is unusual to see bug reports resolved all the way to release within 72 hours.  I think it wasn't abnormal for me to assume otherwise.  Please consider clarifying your policy page, so that bad feelings can not forment from misunderstandings.  I can not read your mind.  You have to state it.

That's a fair assessment, and one that should be addressed.  We 
constantly update the site based on suggestions from users in 
situations that, in all honesty, we may not foresee as part of the big 
picture.  This is an open source project that evolves minute-by-
minute, most often with suggestions and submissions by folks such as 
yourself being implemented over time.

Our documentation team is pretty snappy at getting things accomplished 
quickly, and we're lucky (at least so far) that we don't face 
bureaucratic roadblocks like a lot of other projects can't seem to 
overcome.  It's by no means a guarantee that the bug will be fixed 
within 72 hours, but there's a better chance that it will than it 
won't.

That aside, you seriously may want to consider joining the project.  
You're obviously passionate about it.... why not apply that directly 
without having to go through a middle-man to achieve results?  With no 
word in jest or sarcasm, the PHP project could benefit from your help.

One reason the documentation of PHP's flock() is critical, is for example in my PHP-GTK2 application (a internet cafe timer that is run on customer logon), I need some way to let only one instance of the application run at a time (if customer attempts to run more instances), but I don't want the other application instances blocking-- rather I want them to exit immediately when they detect the lock on the shared file.  So the fact that LOCK_NB is supported on Windows is critical to my application (since I am targetting Windows now, but want *nix OS an option in future).

Also since many people do run on FreeBSD (e.g. my pair.com server account), it is important to know that the underlying OS fcntl implementation, is going to behave incorrectly if the same process does fclose() while also holding a lock on the same file with another file handle.  In fact, that might not be considered a documentation bug, but a real bug where flock(2) instead needs to be used on FreeBSD (and any system implementing the "stupid" Posix.1 standard for fcntl).

Thanks for the invitation to become more involved with PHP, actually I have been contributing infrequent suggestions and bug reports (and a few manual annotations) since as far back as PHP3 and I think I've interacted with rasmus and sniper roughly 6 or 7 years.  I think I was pointing out the need for destructors and other OO features back then.  I remember making a report about the impossibility of reporting error state through JSON due to the way the older PHP had lost its state by the time the error handler got called.

In any case, I've got my fingers in many pies right now, e.g. I recently delved into functional programming and tried to simplify it:

http://www.coolpage.com/commentary/economic/shelby/Functional_Programming_Essence.html
(especially see how I reduced Category Theory and Monads from 10+ pages of goobly-gook mind bending to something easy to grasp by any programmer)

And within 2 weeks of starting to learn it, made a crucial suggestion that was accepted by one of the co-creators of Haskell:

http://hackage.haskell.org/trac/ghc/ticket/3630

Right now, my focus is on trying to move more free lance (less corporate control) programming into developing world, and so I am in extreme rush because I do not feel we have much time, so my passion is driven also by survival of mankind and freedom and general, so that might explain why I am bit touchy and why I take any opportunity I can get to tell people and recruit more to the awareness (I need to calm down for the long-haul, but reading the links about H1N1 may shed some light on my sentiments):

http://goldwetrust.up-with.com/precious-metals-f6/silver-as-an-investment-t33-210.htm#2342
http://www.financialsense.com/fsu/editorials/2009/1109.html

Apologies to everyone for this over-personalized diatribe, and again my apologies for misunderstanding the intent and timing of your policy.  Thanks for being receptive to making your manual annotation policy more clear.

And I do hope this bug report was accurate and helpful.  You guys (any gals?) can determine that.  All the best.  We will cross paths more.

Yes exactly people become jaded by the open source process when it gets bogged down in politics.

I do not have time to go locate that manual annotation submission policy page again, but perhaps I can suggest something:

"Manual annotations should _ONLY_ be used to supplement the understanding of, and experiences with, the official manual text.  When the official manual text is in error, _INSTEAD_ please submit a documentation error bug report at bugs.php.net.  When submitting a documentation error bug report, please do not also submit a manual annotation, because this creates duplication of effort and confusion for us and the PHP community.  Although perfection is not promised, we make best efforts to process documentation error bug reports within 72 working hours, and to apply any accepted change to the mirrors of the official manual text within days."

Also let me suggest you add a feature where people can mark bug reports as applicable to certain manual pages, then have a scrollable list of cross-references on both the manual pages and the bug reports.  Formalize the cross-reference at the DB level, may improve utility and understanding.

This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.