# Call for a doc push - Thread: https://externals.io/message/44376 - Original archive: https://news-web.php.net/php.internals/44376 - Started by Rasmus Lerdorf on 2009-06-19T16:38:27+00:00 - Messages: 9 - Reply by email to internals@lists.php.net - More for agents: search with https://externals.io/search.md?q={query} · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt --- ## #44376 — Rasmus Lerdorf — 2009-06-19T16:38:27+00:00 URL: https://externals.io/message/44376#44376 Guys and gals, in the old days we had a very close tie between the code and the documentation. As the project has grown the two have drifted apart. I think this is mostly because the phpdoc team has done an amazing job keeping up with the code changes and writing awesome documentation. This has made us a bit lazy and complacent. I would like to encourage everyone on this list to spend a little bit of time looking at the parts of the documentation that cover things you are familiar with. Or even just going through some of the doc bugs and helping out in general. To get you started: Checkout the phpdoc tree from cvs Read the README file When you make a change, run "php configure.php" to make sure you didn't break anything, and that is about all you need to know. If you want to build your own version of the full manual so you can see exactly what your changes will look like, do: pear install doc.php.net/phd-beta and run the phd script. It will build the manual and you can create a local docs vhost to look at it, but this is more work and not really necessary if you are just tweaking things and adding to already existing documentation. Personally I am going to try to make one doc commit per day for the next little while. -Rasmus --- ## #44388 — zoe.slattery@googlemail.com — 2009-06-21T10:23:23+00:00 URL: https://externals.io/message/44376#44388 · In reply to: #44376 Hi > Guys and gals, in the old days we had a very close tie between the code > and the documentation. As the project has grown the two have drifted > apart. I think this is mostly because the phpdoc team has done an > amazing job keeping up with the code changes and writing awesome > documentation. This has made us a bit lazy and complacent. > > I would like to encourage everyone on this list to spend a little bit of > time looking at the parts of the documentation that cover things you are > familiar with. Or even just going through some of the doc bugs and > helping out in general. > This reminded me that a while ago I made some opcode documentation available in the form of a set of charts written by Andy Wharmby (http://www.zapt.info/PHPOpcodes_Sep2008.odp) and some opcode samples (http://www.zapt.info/opcodes.html) from the IBM Japan team. I don't think either of these ever made it the PHP docs and as they are still on my personal website and they are somewhat at risk :-/ I heard recently that people were using them (http://tr.im/phpcompilerinternals) so I'd like to put them somewhere more permanent. My current plan is to move them both to sp1.php.net. Does anyone object? Or better still would anyone be willing to integrate them with the PHP docs? Zoe --- ## #44391 — Kalle Sommer Nielsen — 2009-06-21T11:08:13+00:00 URL: https://externals.io/message/44376#44391 · In reply to: #44376 2009/6/19 Rasmus Lerdorf : > Guys and gals, in the old days we had a very close tie between the code > and the documentation.  As the project has grown the two have drifted > apart.  I think this is mostly because the phpdoc team has done an > amazing job keeping up with the code changes and writing awesome > documentation.  This has made us a bit lazy and complacent. > > I would like to encourage everyone on this list to spend a little bit of > time looking at the parts of the documentation that cover things you are > familiar with.  Or even just going through some of the doc bugs and > helping out in general. > I just committed the initial migration guide for 5.3.0: http://news.php.net/php.doc.cvs/4177 Its still very raw and basiclly just a convertion of the UPGRADING file into docbook xml, if anyone find any missing things, or other changes then let them be committed so its ready for the gold release :) > > Personally I am going to try to make one doc commit per day for the next > little while. > > -Rasmus > > -- > > > > -- regrads, Kalle Sommer Nielsen kalle@php.net --- ## #44392 — Gwynne Raskind — 2009-06-21T14:27:25+00:00 URL: https://externals.io/message/44376#44392 · In reply to: #44388 > > […] > This reminded me that a while ago I made some opcode documentation > available in the form of a set of charts written by Andy Wharmby (http://www.zapt.info/PHPOpcodes_Sep2008.odp > ) and some opcode samples (http://www.zapt.info/opcodes.html) from > the IBM Japan team. I don't think either of these ever made it the > PHP docs and as they are still on my personal website and they are > somewhat at risk :-/ > I heard recently that people were using them (http://tr.im/phpcompilerinternals > ) so I'd like to put them somewhere more permanent. My current plan > is to move them both to sp1.php.net. Does anyone object? Or better > still would anyone be willing to integrate them with the PHP docs? Zoe, have a look at :). I don't have anything that can read that ODP file you linked (at least, not in any useful sense), but the opcodes.html file is all there. With any luck, someone else will come along and clean it up a bit, and/or expand on it. -- Gwynne --- ## #44393 — Lester Caine — 2009-06-21T17:02:51+00:00 URL: https://externals.io/message/44376#44393 · In reply to: #44392 Gwynne Raskind wrote: > > > […] > > Zoe, have a look at :). I don't > have anything that can read that ODP file you linked (at least, not in > any useful sense), but the opcodes.html file is all there. With any > luck, someone else will come along and clean it up a bit, and/or expand > on it. http://enquirysolve.co.uk/fisheye/view_image.php?image_id=3790 Is the Opcode paper as a PDF, but it's simply an OpenOffice presentation so doesn't need anything 'expensive' to read and edit it. -- Lester Caine - G8HFL ----------------------------- Contact - http://lsces.co.uk/wiki/?page=contact L.S.Caine Electronic Services - http://lsces.co.uk EnquirySolve - http://enquirysolve.com/ Model Engineers Digital Workshop - http://medw.co.uk// Firebird - http://www.firebirdsql.org/index.php --- ## #44401 — zoe.slattery@googlemail.com — 2009-06-22T09:22:49+00:00 URL: https://externals.io/message/44376#44401 · In reply to: #44393 Hey Gwynne > > […] > Brilliant! Thanks. > http://enquirysolve.co.uk/fisheye/view_image.php?image_id=3790 > Is the Opcode paper as a PDF, but it's simply an OpenOffice > presentation so doesn't need anything 'expensive' to read and edit it. > Lester - this helps. The reason that I made the .odp available was so that people would be able to update it - this kind of information tends to get out of date and I think Andy did that work almost two years ago :-/. I can't think of a better way than .opd or .pdf right now either. I guess it really needs converting into a set of pictures that could be embedded in documentation as part of the manual, I have a feeling this might be a lot of work. Zoe --- ## #44404 — Lester Caine — 2009-06-22T10:47:51+00:00 URL: https://externals.io/message/44376#44404 · In reply to: #44401 zoe wrote: > Hey Gwynne > > […] > Brilliant! Thanks. > > […] > Lester - this helps. The reason that I made the .odp available was so > that people would be able to update it - this kind of information tends > to get out of date and I think Andy did that work almost two years ago :-/. > > I can't think of a better way than .opd or .pdf right now either. I > guess it really needs converting into a set of pictures that could be > embedded in documentation as part of the manual, I have a feeling this > might be a lot of work. Of cause the nice thing with OpenOffice is you just hit the .pdf button on the top and out that copy comes FOC! I've finally converted a couple of my customers from Office and they now create all the pdfs directly without me having to try and sort the layout mess from the .doc files :) And the html copy is much more usable as well. -- Lester Caine - G8HFL ----------------------------- Contact - http://lsces.co.uk/wiki/?page=contact L.S.Caine Electronic Services - http://lsces.co.uk EnquirySolve - http://enquirysolve.com/ Model Engineers Digital Workshop - http://medw.co.uk// Firebird - http://www.firebirdsql.org/index.php --- ## #44444 — Hannes Magnusson — 2009-06-23T19:48:24+00:00 URL: https://externals.io/message/44376#44444 · In reply to: #44376 > Personally I am going to try to make one doc commit per day for the next > little while. Thats very much appreciated. Also, if people who added new features (language level, extensions, classes, methods, functions, arguments, mode options, format options, constants, error messages......) could please add them to the UPGRADING file. It is very hard to go through all these hidden bugfixes that magically added new features without even referencing that in the bug report itself. Just by updating the UPGRADING file you will increase the chance of the feature actually making it to the end-user by 100%, and getting it documented "for free" by 75%. And as we all know, 82.5% of all stats are made up on the spot. -Hannes --- ## #44447 — Greg Beaver — 2009-06-23T20:21:11+00:00 URL: https://externals.io/message/44376#44447 · In reply to: #44444 Hannes Magnusson wrote: > Just by updating the UPGRADING file you will increase the chance of > the feature actually making it to the end-user by 100%, and getting it > documented "for free" by 75%. And as we all know, 82.5% of all stats > are made up on the spot. The best part is that 60% of the time, it works every time. Greg