[PHP-DOC] Re: [PHP-DEV] Moving PHP documentation to Git repository
On 25.06.2013 08:46, Christian Stoller wrote: What do you think about moving the PHP documentation to a Git repository, mirrored on Github? Doing this would make it possible for everybody to extend the documentation easily by creating pull requests. snip What do you think? Even from a purely selfish point of view, I'm a big fan of migrating to Git: it would make developing documentation for big chunks of work (migration guides, significant new extensions, and so on) much easier by allowing that work to take place in a fork, or on a local branch. If it helps other people to collaborate as well, so much the better. Plus, again selfishly, it would remove the last thing I use SVN for. :) The tooling argument's a fair one, though, and something that we'd have to work through. Adam
Re: [PHP-DOC] Re: OPCache documentation
On 20 June 2013 14:36, Julien Pauli jpa...@php.net wrote: On Wed, May 15, 2013 at 3:54 PM, Julien Pauli jpa...@php.net wrote: Hi all, As you know, 5.5 final is coming soon. We are in RC, so mainly stabilizing stuff and preparing the final release for anyone to setup 5.5 on their servers. I see the documentation migration guide has already been commited, that's a good new. I also see that new features we ship in 5.5 are online in the documentation, great ! But a crucial feature is missing doc : OPCache. As this feature is a very big step in PHP's life (we finally have a recommanded, bundled opcode cache system, and I'm very proud of this personnaly), I think it is crucial to have a good documentation about it. Has anyone started to write some doc about OPCache ? Another subject is APC. We have its doc on php.net, all right. What I would like is we patch APC doc when 5.5 final gets released, to clearly show our mind about it. That way, any people using 5.5 should be able to read in the doc that APC has support has been interrupted, that APC should never be used together with OPCache, and that OPCache is now the standard recommanded OPCode caching solution for 5.5, 5.4 and 5.3. It is crucial to communicate one this point for our users. Then will come the User cache debate Thank you. Up. Could we at least plan such a project ? 5.5 is released now. I know we are still having trouble about OpCache particulary under Windows. I dont shadow that. I would just like we start thinking about writing documentation for OPCache features and merge them to our official documentation. If it's already planned by someone, just let me know ;-) I'm working on some basic opcache documentation as we speak, since it was pointed out on #php.doc. That said, mostly what I'm doing for now is adapting the README in ext/opcache and documenting opcache_reset() and opcache_invalidate() — some additional theory of operating and setup documentation would be very welcome. There should be something to look at in SVN in the next hour or so. My apologies — I wrote the first draft of the migration guide in the mid alpha stage (ie before opcache was merged) of 5.5 with the intention of going back to flesh it out before the final release, but time has been a bit of an issue. Turns out moving halfway across the world is a real time sink. Adam
Re: [PHP-DOC] Re: strlen and multi-byte characters
On 16 June 2013 15:37, Sherif Ramadan theanomaly...@gmail.com wrote: I have no clue how you're getting that result. What are your respective mbstring.func_overload settings, out of interest? Adam
Re: [PHP-DOC] FR - Need help
On 12 June 2013 13:18, Yannick Torrès yannick.tor...@gmail.com wrote:
The FR documentation actually didn't build.
configure.php don't tell me where, nether with the --enable-xml-details :/
Is there someone who can help us with this ?
Here's the first part of what I get (the important bit would seem to
be the class.datetimeinterface issue — I think German had the same
issue recently?):
configure.php: $Id: configure.php 328371 2012-11-15 22:48:10Z philip $
PHP version: 5.5.0-dev
Checking for source directory... /home/adamh/trees/php-doc-fr/doc-base
Checking for output filename...
/home/adamh/trees/php-doc-fr/doc-base/.manual.xml
Checking whether to include CHM... no
Checking for PHP executable... /opt/php/5.5/bin/php
Checking for language to build... fr
Checking whether the language is supported... yes
Checking for partial build... no
Checking whether to enable detailed XML error messages... yes
Checking libxml version... 2.9.0
Checking whether to enable detailed error reporting (may segfault)... no
Checking whether to optimize out the DTD (performance gain, but
segfaults)... yes
Generating /home/adamh/trees/php-doc-fr/doc-base/manual.xml... done
Generating /home/adamh/trees/php-doc-fr/doc-base/install-unix.xml... done
Generating /home/adamh/trees/php-doc-fr/doc-base/install-win.xml... done
Generating /home/adamh/trees/php-doc-fr/doc-base/developer.template.xml... done
Generating /home/adamh/trees/php-doc-fr/doc-base/scripts/file-entities.php...
done
Iterating over extension specific version files... OK
Saving it... OK
Creating file
/home/adamh/trees/php-doc-fr/doc-base/entities/file-entities.ent...
done
Checking for if we should generate a simplified file... no
Checking whether to save an invalid .manual.xml... no
Loading and parsing manual.xml... done.
Validating manual.xml...
Warning: DOMDocument::xinclude(): XPointer evaluation failed:
#xmlns(db=http://docbook.org/ns/docbook)
xpointer(id('class.datetimeinterface')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='oop'])
in /home/adamh/trees/php-doc-fr/doc-base/configure.php on line 686
Warning: DOMDocument::xinclude(): could not load
/home/adamh/trees/php-doc-fr/doc-base/manual.xml, and no fallback was
found in /home/adamh/trees/php-doc-fr/doc-base/configure.php on line
686
Warning: DOMDocument::validate(): Element classsynopsis content does
not follow the DTD, expecting ((ooclass | ooexception | oointerface)+
, (classsynopsisinfo | methodsynopsis | constructorsynopsis |
destructorsynopsis | fieldsynopsis)*), got (ooclass classsynopsisinfo
classsynopsisinfo fieldsynopsis fieldsynopsis fieldsynopsis
fieldsynopsis fieldsynopsis fieldsynopsis fieldsynopsis fieldsynopsis
fieldsynopsis fieldsynopsis fieldsynopsis classsynopsisinfo
constructorsynopsis methodsynopsis methodsynopsis methodsynopsis
methodsynopsis methodsynopsis methodsynopsis methodsynopsis
methodsynopsis methodsynopsis methodsynopsis methodsynopsis xi:include
) in /home/adamh/trees/php-doc-fr/doc-base/configure.php on line 728
Warning: DOMDocument::validate(): No declaration for element include
in /home/adamh/trees/php-doc-fr/doc-base/configure.php on line 728
Warning: DOMDocument::validate(): No declaration for attribute
xpointer of element include in
/home/adamh/trees/php-doc-fr/doc-base/configure.php on line 728
failed.
The document didn't validate, trying to figure out what went wrong...
(This could take awhile. If you experience segfaults here, try again
with --disable-xml-details)
Warning: DOMDocument::load(): No declaration for attribute xpointer of
element include in
file:home/adamh/trees/php-doc-fr/fr/language/predefined/exception.xml,
line: 64 in /home/adamh/trees/php-doc-fr/doc-base/configure.php on
line 785
big snip
Eyh man. No worries. Happ shittens. Try again after fixing the errors above.
Full output is at
https://gist.github.com/LawnGnome/ad5d1c897437085795c8, should it be
useful.
Adam
[PHP-DOC] Re: [PHP-WEBMASTER] PHP Manual is missing some index entries - Is this a bug or they have been removed ?
On 26 May 2013 02:06, Manmohan Bishnoi manmohan.bish...@gmail.com wrote: Just wanted to know that whether this is a BUG or the documentation structure has been under major changes ? This is a bug — specifically, https://bugs.php.net/bug.php?id=64842, I believe. I don't think anyone who knows about CHM generation has had a chance to look at it yet. Thanks, Adam
[PHP-DOC] Re: [DOC-BUGS] Doc #64909 [Opn-Nab]: array_merge - Return value documentation incorrect/misleading
(Cross-posted from the bugspam list.) On 25 May 2013 12:10, sala...@php.net wrote: This behaviour is common across almost all functions, and we have a note to that effect on the Internal (built-in) functions page (http://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. The documentation team have discussed this in the past and determined that it would be impractical and confusing for readers if such a note were to be added to every-single-function in the manual. I know I've previously signed up for this line of thought too, but I've been thinking about that a bit, and I wonder if we are actually right here. As things stand, the return values section for almost all functions is actually incomplete — I think it's a reasonable expectation that reference pages should be reasonably self-contained, and right now they're not: our description of inputs and outputs usually doesn't cover the rather common case where an input variable is the wrong type for whatever reason. I think we should define an entity that could be the final paragraph of most return value sections that reads something like: Returns NULL if parameters of the wrong type are provided. Actually adding that to function pages could probably be done in a semi-automated manner — it's not particularly hard to test if an internal function does actually exhibit the NULL on incorrect type behaviour. Does anyone have any thoughts for or against? I don't mind doing the work next time I have some free time on a Sunday, but I need to know if I'm not the only one who thinks it's a worthwhile change before doing so. :) Adam PS: Sorry for picking on your comment, Peter. This has been percolating in my head for a while, so it's nothing personal!
Re: [PHP-DOC] Re: [DOC-CVS] svn: /phpdoc/en/trunk/ .travis.yml
On 21 January 2013 09:08, Ferenc Kovacs tyr...@gmail.com wrote: http://about.travis-ci.org/docs/user/notifications/ we don't have a custom notifications set up, so the default behavior will be used when sending out the email on broken builds. Is the owner of the repository in this case phpdoc@lists.php.net? I would think we'd definitely want e-mails to come here (and could then retire the checking script in cron if it works out). Adam
[PHP-DOC] Re: [PHP-WEBMASTER] User notes guidelines.
On 10 January 2013 02:05, Levi Morrison morrison.l...@gmail.com wrote: Firstly, I apologize if this is the incorrect list. It's more phpdoc and php-notes, so I've cc:d those lists in. Thanks for pitching in! Here's some background reading from a user note discussion last year: http://marc.info/?l=phpdocm=134639945511076w=2 — I also reviewed a whole heap of notes to try to categorise them, except I was trying to kill the feature totally. :) (I got better.) There have also been a bunch of IRC discussions on #php.doc at various times around user notes. I'm trying to crystallise my understanding of those below, but I expect other people will disagree with me. 1. Code snippets to do something similar to the current function. 2. Reports of performance compared to function X. Incorrect testing methods are usually involved. 3. Reports an edge-case not included in the manual section. Some pages of the manual have severe problems with #1. See http://php.net/manual/en/function.count.php for an example one such page. A blanket policy of deleting notes like this would probably be harmful, but on this page in particular I feel like deleting all comments of this type. What really bothers me about #2 is that the testing methods are usually skewing the results. I don't feel like editing is appropriate in these situations but am unsure if deletion is appropriate either. When in doubt, we generally tend towards deletion. (I probably have the heaviest hand of anyone on this front, but I'm not alone in the philosophy.) If you look at the archive of the notes ML, you'll note that periodically, someone (probably Sherif, Dan or I in recent times) will get frustrated with the state of a page and will cull the worthless notes. On bigger pages, that's often 50+ notes. It sounds like count() is due for that. In the case of #3 I feel like we should simply update the manual. The question then becomes: should we keep the comment? Generally, no — if the manual's been updated, then the note should be removed. Related: is there a posted guideline for moderating user contributed notes? We don't have a lot written down that I'm aware of. My own opinion is: - Questions and support requests should be rejected (so that the submitter gets an e-mail). - Useless notes get deleted. Defining useless is left as an exercise for the moderator, although the quick deletion reasons in the automated note e-mails do provide a rough guide (they are: integrated, useless, bad code, spam, non-english, in docs, other reasons). - Real bugs get turned into bug reports, then deleted. - Responses to previous notes should usually result in the previous note being edited or deleted, and the response being deleted, since user notes aren't intended to be a conversation thread. That doesn't tend to leave a lot, admittedly. (Which is one of my frustrations with the whole feature.) Thanks again, Adam
Re: [PHP-DOC] Fixing the layout/style for man pages
On 29 December 2012 07:04, Levi Morrison morrison.l...@gmail.com wrote: 1. The documentation pages need to be full-page width. They are far too narrow in their current state. They also need more gutter room. Weirdly, I think they're more readable in their current state than full width. I seem to be outnumbered here, though. :) 2. Kill the Quick TOC in the documentation. This frees up a lot of space, but means we need to find a new home for the language switcher and how to report an error. We have a pull request on GitHub to deal with this: https://github.com/php/web-php/pull/8. I'm not crazy about the styling of it at the moment, but the functionality in terms of switching to a sticky TOC box might be worth pursuing. Here's how it looks when you haven't scrolled: http://d.pr/i/gTlC And how it looks when you have: http://d.pr/i/K8se Adam
Re: [PHP-DOC] This PHP Manual build is broken
On 20 December 2012 16:06, nore...@php.net wrote: The en build of the PHP Manual is broken, so it does not validate or build. Please fix it! ;) Fixed. Insert the usual reminder about the benefits of checking your commits through configure.php before committing them. :) Love, The docs.php.net server Indifference, Adam
Re: [PHP-DOC] VCS Account Request: dm
On 21 December 2012 07:29, Philip Olson phi...@roshambo.org wrote: appears moderately sane You don't have to be crazy to work here, but it helps. Welcome aboard! Adam
[PHP-DOC] User notes
tl;dr: I am become death, the destroyer of user notes. (I hope.) Hi everyone, As many of you know, user notes have been a long-standing hobby horse for me. About six weeks ago, I decided to do something useful about them, and subscribed to the mailing list to try to help moderate the stream of incoming user notes more effectively. My opinion of user notes was already that they were generally not particularly worthwhile, but a few weeks of consuming the firehose has changed that. I now think they're actively harmful. To illustrate my point, here's a breakdown of the last 200 submitted user notes: Type NotesPercentage Non-useful code sample 3920% Something already in the manual 2613% Support request 2513% Reply to previous note 2211% Actually useful note16 8% Documentation bug report/improvement13 7% Useful code sample 13 7% Not PHP related at all 11 6% Correction of previous note 9 5% WTF? 9 5% Bug report 8 4% Link to unrelated site/spam 5 3% Link to related site 2 1% Duplicate2 1% Now, obviously the categorisations are subjective. I tried to be as generous as possible when rating a note or code sample as useful: if it was something that I considered obvious or was documented elsewhere, but wasn't really dealt with in the section the note was in, I considered it useful. By that metric, about 15% of the notes submitted are actually of real utility. That's a lot of noise and not much signal. The added problem is that a lot of the non-useful samples aren't just poor quality. Many are genuinely harmful: they include poor security practices, deprecated code, and various other things that, unfortunately, being on *.php.net masks, since many users give user notes equal authority to the manual itself. Plus I can see three possible ways forward: 1. No change. As things stand, the only people who seem to look regularly at the new notes are Dan and myself, with a few others (including Sherif, Nikita and Peter) cleaning out particular pages. If you pick a reasonably commonly hit page and look at the user notes, I don't think this approach is scaling. 2. Kill user notes completely. The new site design (I'm getting to that in another e-mail in the not-too-distant future, hopefully) has more prominent links for reporting bugs and going to the online editor, so I'm hopeful that we might actually get the useful feedback listed above via those means instead, and can then incorporate them into the manual proper. 3. Replace user notes with something more comment-based: either something on-page like Disqus (which probably doesn't get us much other than comment threading for better conversations and a shitty UI), or linking to something like StackOverflow (maybe we see about getting a PHP-specific, officially-blessed StackExchange, with links from function references to tags?). One road I don't particularly want to go down is adding significant additional functionality to our own user notes: our backend would require a decent amount of work, and I think there are better solutions out there we could leverage. Thoughts? Am I completely on the wrong track? Are the PR benefits of user notes enough to outweigh the amount of crap^Wnoise they contain? Thanks, Adam
[PHP-DOC] Re: [PHP-WEBMASTER] User notes
On 31 August 2012 21:56, Daniel Brown danbr...@php.net wrote: On Fri, Aug 31, 2012 at 6:16 AM, Hannes Magnusson hannes.magnus...@gmail.com wrote: It isn't scaling, but we do have crapload of people with php.net karma, and all of them have the ability to edit/reject notes.. Most simply don't know it. I think we should try to reach out the individual extension maintainers and get them to review their own pages. That's a really good idea, Hannes. I vastly reduced my moderation activity this spring in hopes others would think I was killed by a bear and would join in. Having each extension's author look through periodically, though, would be a great help. Derick used to prune the time sections every few months, but I think he's just gotten so busy that he really just doesn't have the well time. Agreed. I think that's got the potential to improve matters considerably. (The key word being potential.) Unfortunately, though, I'm not sure how many people would actually want to be bothered, and without using firearms, there's little we can do to force them. Those that would might not have the time or interest in doing so regularly or diligently. That's definitely my concern, too. And, Adam, while that's really quite impressive that you'd taken the time and effort to put stats together (and, in many cases, I'd be inclined to agree with your rating), it's all subjective. I completely agree. :) That said, things I've done to try to reduce the fluff (read: crap) in the notes have failed miserably --- and that's putting it lightly. I mean that it's been met with such catastrophic failure that the Hindenburg looks like a roller coaster for small children by comparison. I've followed up with contributors who left a valid email address to discuss ways to improve their note and resubmit it for acceptance. I added explicit what not to enter information. I even tried placing an XKCD comic as a masthead on the note submission page to grab attention. In all, it seems we can't prevent the milk from spilling, we can only clean up the mess after. Yeah, and to be clear: I'm not having a go at anyone's efforts here, especially yours. You do a power of work here. I've done some of this myself: I've also followed up with contributors. I've turned a couple of notes into doc bugs and commits, and should convert a few more. It just feels like nailing jelly to the wall at times, and I haven't been doing this for anywhere near as long as you have — for the most part, I've spent the last few years ignoring notes altogether. I don't know exactly what the solution is, but I do believe it is best managed in-house. On that, there seems to be general agreement. Message received loud and clear! So, assuming we're going to keep notes as seems to be the consensus so far: what can we do to make them more manageable? (Yes, I'll help write code.) Adam
Re: [PHP-DOC] This PHP Manual build is broken
On 6 August 2012 15:05, nore...@php.net wrote: The en build of the PHP Manual is broken, so it does not validate or build. Please fix it! ;) I've reverted r326993 for now, which caused the breakage. Herman, did you forget to svn add the GearmanException documentation? Thanks, Adam
Re: [PHP-DOC] This PHP Manual build is broken
On 24 July 2012 15:04, nore...@php.net wrote: The en build of the PHP Manual is broken, so it does not validate or build. Please fix it! ;) Fixed. Appropriate person whacked with newspaper. Love, The docs.php.net server Kisses, Adam
Re: [PHP-DOC] [DOC-EN] - Your documentation is broken
On 4 May 2012 04:05, phpdoc@lists.php.net wrote: Your documentation is broken. The build is done on Friday. Fixed. Usual admonishments about checking that your XML is valid before committing apply. :) Adam
Re: [PHP-DOC] GSoC 2012
On 22 February 2012 10:50, Philip Olson phi...@roshambo.org wrote: If we want to join the GSoC then I'm guessing we'll need to lead the charge. Please speak up if you're willing to administrate the GSoC for the entire PHP project. I did put my hand up for that on IRC a week or two back, so I'm still fine with that if need be. Also, here's the general ideas page for the PHP project: - http://wiki.php.net/ideas Some of this is pretty out of date (referring to the FPM patch as a patch, for instance), so the first step is going to be pruning back the list to what still makes sense. We've basically got about two weeks to whip this into shape, gather new ideas, find mentors, et cetera. Adam
Re: [PHP-DOC] [DOC-EN] - Your documentation is broken
On 21 February 2012 05:00, phpdoc@lists.php.net wrote: Your documentation is broken. The build is done on Friday. Fixed. Insert usual grumble about people not running configure.php here. :) Adam
Re: [PHP-DOC] [DOC-EN] - Your documentation is broken
On 16 February 2012 05:00, phpdoc@lists.php.net wrote: Your documentation is broken. The build is done on Friday. Please, try to fix it *quickly*. Just under four hours. I'm going to call that quick. Build fixed. Adam
Re: [PHP-DOC] Updating our credits system
On 21 July 2011 07:15, Hannes Magnusson hannes.magnus...@gmail.com wrote: A (short) list of authors or a group needs to exist due to licensing issues. How to generate that one I've no idea. Are you sure about that? I think you'll find that copyright is held by all contributors individually, so it's actually more accurate to point to the entire list for licensing purposes. I would like a NEWS/ChangeLog listing, similar to what php-src does. That would serve the dual purpose of improving crediting of people actually working on the docs on daily basis, and letting the user know what is new within the docs (so he can pay attention to modifications to his favorite doc page), and bugfixes etc etc. It would be nice. We should be able to auto-generate something, really, based on commits. Adam
Re: [PHP-DOC] expanding the security section in the documentation
On 27 April 2011 11:10, Daniel Convissor dani...@analysisandsolutions.com wrote: On Fri, Apr 22, 2011 at 10:08:20AM +0200, Hannes Magnusson wrote: There was at some point discussion about merging the http://phpsec.org/ doc into the manual, but I think that went nowhere as those peeps didn't want to play ball. As one of the people there, I don't see a problem with it and believe that the majorit of the other folks there would be okay with it being in the PHP manual. Let alone, it's an open license document. It is, but not one that's compatible with the PHP Manual: the PHP Security Guide is CC-BY-NC-SA 2.0, whereas the PHP Manual is CC-BY 3.0. The Security Guide would have to be explicitly relicensed (or dual licensed) by its authors before it could be incorporated into the Manual. Adam, who swore he'd never write a mailing list post about licensing. So much for that.
Re: [PHP-DOC] Official movement to clean old PHP versions from the documentation
On 28 January 2011 10:53, Daniel Convissor dani...@analysisandsolutions.com wrote: A quick reminder that one thing that seemed to be agreed upon during the last discussion is that mentions of older versions in the text (like available since) should be moved to the change log on the given page. I think that's a good general rule, but I think we need to be flexible in cases where functions have undergone major changes (especially security impacting ones): something like crypt(), for example, has undergone so many changes in 5.3.0 and 5.3.2 that it would actually be unfair on the users not to leave the note in the synopsis about the availability of hash functions. Adam
Re: [PHP-DOC] Official movement to clean old PHP versions from the documentation
On 15 January 2011 23:46, Daniel Brown danbr...@php.net wrote: On Sat, Jan 15, 2011 at 05:52, Julien Pauli jpa...@php.net wrote: Last time (http://marc.info/?l=phpdocm=128686832705180w=2) , we suggested that [old-and-not-supported-versions] = PHP4 + PHP5.0 + PHP5.1 ; and [up-to-date-versions] = PHP5.2 + PHP5.3 -1 Getting rid of PHP4, sure, but I think it's a horrible idea to get rid of all PHP 5.2 references. Agreed. I'd probably add 5.0 to the list of releases that could be removed from the manual, but 5.1.6 is still the standard PHP version Red Hat ship in RHEL 5 (although they've at least added an optional set of 5.3 packages in RHEL 5.6), so we should probably continue to document 5.1 as long as RHEL 5 is in wide use. Adam
Re: [PHP-DOC] Integer set unicode character
On 10 January 2011 17:02, Karoly Negyesi kar...@negyesi.net wrote: This http://paste.pocoo.org/show/318170/ would be more correct but it contains a non ASCII Unicode character. May I commit it still? Documentation files are explicitly UTF-8 (per the XML header), so as long as the ℤ is encoded in UTF-8, it should just work — I've just tested a partial build with that change and it builds and renders as expected. Adam
Re: [PHP-DOC] This PHP Manual build is broken
On 6 January 2011 14:15, Apache nore...@php.net wrote: The build of the PHP Manual is broken, so it does not validate or build. Please fix it! ;) Fixed in r307153. Love, The docs.php.net server Hugs and kisses, Adam
[PHP-DOC] Re: [PHP-DEV] Potential PC conflict.
On 8 November 2010 19:00, Richard Quadling rquadl...@gmail.com wrote: [1] vs [2] Not asking for a change or anything. I think it's probably OK the way it is: the manual page is specifically for MongoId, and the capitalisation's quite distinct from any other meaning there. The URL might be a touch unfortunate, but I don't think it's worth worrying about, personally. Adam
Re: [PHP-DOC] License for code examples in the PHP manual?
On 3 October 2010 08:43, Robinson Tryon bishop.robin...@gmail.com wrote: Is there any chance that the code examples in the manual are also available under a different license as well? As you've seen on the licensing page, the manual — including the code examples — is only available under the CC-BY licence. Given the number of contributors over the years, I think it's unlikely that we'd be able to relicense (or dual license) to anything else at this point. Adam
Re: [PHP-DOC] Documentation update for IBM_DB2 extension (db2_pconnect API)
Hi Ambrish, On 16 September 2010 16:58, Ambrish Bhargava1 abhar...@in.ibm.com wrote: With the release of v1.9.0 of IBM_DB2 extension, one documentation change is required for db2_pconnect() API. Attached patch file contains the changes. The change log corresponding to this documentation can be seen at: http://pecl.php.net/package/ibm_db2/1.9.0 Can anyone commit this patch? Thanks for the patch. I've committed a slight variation on what you suggested as a normal paragraph in the function description, rather than as a note within the description, which seems to fit more visually within the page. I've also used this and the description of the options that have been added over the various versions of ibm_db2 section to create a change log on the db2_pconnect() function page. Thanks again, Adam
Re: [PHP-DOC] Bug #51834 set to bogus, your thoughts?
On 2 June 2010 01:21, Alex Cartwright alexc...@googlemail.com wrote: As a use case: Harry visits the FAQ to see what the value of 'K' means, it shows that K means 1 Kibibyte. As Harry knows what a Kibibyte is, he knows that 'K' should be 1024 bytes. Adam on the other hand, has no idea what a Kibibyte is and so continues to read the FAQ which states that 1 Kibyte = 1024 bytes (like the documentation currently does, albeit with wrong wording). I do know what a kibibyte is, thank you! :P (Sorry, couldn't resist. Moving on...) My point being is that those who know the real value can continue to use the real value; those that don't can either A) read a few words further or read up on what a 'kibibyte' is, which takes less than 10 seconds. Something any competent developer should be able to do. Given the number of supposedly competent developers who seem to miss important bits of PHP manual pages as it is, I don't hold out as much hope as you do on that front. Additionally, kilobyte is, in my experience, still the standard term for 1024 bytes in most technical environments. I just conducted a quick (and admittedly extremely unscientific) poll of half a dozen coworkers (a mix of programmers and admins), and when asked what a kilobyte was, all answered 1024 bytes, not 1000 bytes. Honestly, this seems like an advocacy issue to me, and I don't think the PHP manual is the right place to be advocating the adoption of specialist binary prefixes. I'd prefer to go with whatever common usage is, and 2¹⁰ still seems like the common usage to me. Adam
Re: [PHP-DOC] Plagiarism Checker in PHP
On 2 May 2010 20:56, Partha Sarathy parth...@gmail.com wrote: Could you please tell / suggest me how to develop Plagiarism Checker feature or send some useful articles / free APIs and so on. Please note that this mailing list is intended for discussing the development of the PHP documentation, and is not a general support list. You may wish to try one of the support options listed at http://php.net/support instead. Adam
Re: [PHP-DOC] What to do with PHP 6
On 31 March 2010 22:25, Christopher Jones christopher.jo...@oracle.com wrote: 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. Agreed. We can always reincorporate documentation for any features that are backported to the new 5.3-based trunk, but since most of them are going to be Unicode-related, I don't think there's any need to keep them user-visible for now. Adam
