On Sun, 2 Feb 2003 03:13:46 -0700 Zak Greant <[EMAIL PROTECTED]> wrote:
> On Sun, Feb 02, 2003 at 10:43:33AM +0100, Gabor Hojtsy wrote: > ... > > > Hrm. Maybe we could use the work in the PHP Function Essential > > > Reference as the starting point for a new set of docs? At the publish > > > date, it covered a large portion of PHP. > > > > > > This would avoid the licensing issues. People who have already > > > contributed to the documentation could take their specific sections > > > and recommit them to the new docs - even though they contributed to a > > > GPL-licensed work, they still own copyright on their own work. > > > > Well, I think starting off with the new contents is not a good idea. > > First it will be a long time to complete the DocBook version, second thw > > user notes on pages will go useless, as they relate to the current > > documentation and not the book's text. So I think if we can use the > > contents the other way round, then it would be much better for our > > users, and for ourselfs too. > > Heh. The content is already in docbook and the user notes are mostly > useless already. ;) I hope you meant they are outdated in some parts. Because, the user notes are very very usefull for tons of people. It 1) suggests a function's usage 2) extends the documentation (often they are bugs and/or what is getting into the official description). Though a cleanup would be good. What I would also like to see in user notes are the examples. Something that allows someone to choose whether it is a note or this adds an additional example of usage for the given function. Not sure if I render you the idea, but the point is to have a comments of the function and the code serving as a sample of usage separate and clearer, perhaps even highlighted. Also, i think when rethinking the docs we should update the protos where the return types are confusing. With move from PHP3 to PHP4 many functions changed to return True and false instead of 1 and -1. This I addressed in a message a few month ago: http://groups.google.com/groups?q=maxim+maletsky+phpdoc&start=10&hl=en&lr=&ie=UTF-8&oe=UTF-8&selm=20021109043833.EF1C.MAXIM%40php.net&rnum=18 the answer I got was: "we've got no time - go ahead". It's kind of a lot of work here. can we approach it with some more clever method? Is that important anyway? I'd like this to be fixed, though. +1 on all the rest -- Maxim Maletsky [EMAIL PROTECTED] -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
