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
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
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, have a look at http://news.php.net/php.doc.cvs/4180 :). 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
Gwynne Raskind wrote:
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, have a look at http://news.php.net/php.doc.cvs/4180 :). 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
Hey Gwynne
Zoe, have a look at http://news.php.net/php.doc.cvs/4180 :). 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.
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
zoe wrote:
Hey Gwynne
Zoe, have a look at http://news.php.net/php.doc.cvs/4180 :). 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.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.
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
2009/6/19 Rasmus Lerdorf rasmus@lerdorf.com:
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
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
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