Indeed, here (Lima, Peru) I had done some app reviews where the code was copied either from the PHP Manual or from the notes, even from the examples on how not do things in the security chapter. It would be funny if (at least in one case) this code was not being used for sensitive stuff (tracking treatments for ambulatory mental patients).
If memory serves, at some point there were places that hosted code snippets. How about, and this is a pie-in-th-sky idea, if we offer something like that, a community-ranked collection of snippets, that may be associated to one or more manual pages. Not sure if it is needed, useful or relevant or cost-effective (in terms of the effort that needs to be put to build and maintain the thing), but it might be a way to offload all those examples that now hang ungainly from the manual. Cheers. -- Jesus M. Castagnetto <je...@castagnetto.com> Web: http://www.castagnetto.com/ On Tue, Mar 13, 2012 at 07:30, Hannes Magnusson <hannes.magnus...@gmail.com>wrote: > On Sun, Mar 11, 2012 at 10:04, Maciek Sokolewicz > <maciek.sokolew...@gmail.com> wrote: > > > > On 11 March 2012 02:40, Jesus M. Castagnetto <je...@castagnetto.com> > wrote: > >> > >> Sorry to come so late in this discussion. But there are guidelines for > >> more than a decade on how to handle notes: > >> > >> http://doc.php.net/php/dochowto/chapter-user-notes.php > >> > >> Just in case you did not see it: > >> > >> User Note Editing Guidelines > [...] > >> > >> If you are in doubt about what to do with a note, you may ask for help > on > >> the php-notes mailing list (or phpdoc, if what you're doing involves the > >> documentation proper). > >> > >> > >> > > Hi Jesus, > > > > I know those guidelines exist, I even linked to them from my original > post. > > However, those guidelines aren't very complete. They give a very rough > > overview, which I agree with completely. There are tons of notes however, > > which fall somewhere in between the categories supplied in the > guidelines. > > > > What I'm mainly trying to say is that I personally think we don't need a > > zillion examples of how to use a basic function to perform a specific > task. > > Most notes (these days) contain such code. Some are still quite general > (ie. > > people post an example of how preg_split can be used to limit a sentence > to > > a number of words), others are extremely specific (ie. I've seen posts > where > > people show a function to the amount of days between carnival and > easter) or > > possibly numerous with a little usefulnus, but mainly a lot of cluttering > > (ie. people post date() monthnames in different languages, spanish, > russian, > > chinese, french, german, etc. There were at least 30 of these last time I > > checked. Too many to add as an example, and so many that they obscure > other > > notes). > > > > My problem with all this is that it's usually not general enough to > > integrate into the manual itself. Because when I view the manual, I want > to > > know how a function works, I don't care for an extremely specific use of > the > > function for a task that I don't even understand by itself. > > The second problem I have with such things is that there are simply too > many > > notes for certain functions present in my opinion. When you have more > than > > 100 notes(!!) on a single page, finding the one thing you want is neigh > > impossible. Ronald argued against this, while I think it is important to > > moderate them more strictly and keep not only the manual itself, but also > > the notes, more readable. > > > > I was hoping this last part would spark some more discussion, but > > unfortunately, it has not. > > > Its a very difficult topic. On one hand, I completely agree with you - > but on the other hand I know crapload of people that actually do > copy&paste programming exclusively from the manual notes. > Its is a sick thing to watch, but this is exactly why PHP is so cool. > Anyone can create cool stuff, and the amount of random examples in the > notes is crucial for the novice adoption. Everyone has to begin > somewhere. > > -Hannes >
