[PHP-DOC] Re: [PEAR-CORE] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
Hi all, Why not? Getting any errors? I thought it was installed by default by the installer? I guess its because the installer doesn't support folders with spaces as the directory is called C:\Users\Kalle Sommer Nielsen\ So you cannot get further or atleast I can't because my username has spaces. I had to edit the phd.bat manually to make it work, not that it was any major but anyway. The bug has been reported on PEAR 1.7.0 QA testing last year: http://news.php.net/php.pear.qa/4597 http://news.php.net/php.pear.qa/4629 http://news.php.net/php.pear.qa/4604 Greg, did you do anything related to it? I don't see any further replies to the mails. -- Regards/Mit freundlichen Grüßen Christian Weiske -= Geeking around in the name of science since 1982 =- signature.asc Description: PGP signature
[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
On Wed, 2008-10-01 at 14:06 -0500, Greg Beaver wrote: I agree with Liz's appraisal of setting up docs for documenting. This could actually be solved with a minimal VMWare appliance that is pre-setup with everything we need to do the docs (not sure how hard that is to do). VMware works great on windows and the version we would need is free. As Hannes said: All you need is PHP, PhD and a docbook checkout. The later one will be outdated anyways when fetching the VMWare-Image and I assume it's harder to learn how to use the VMWare image than installing these thing, never did that on Windows, but on my *nix it's a shot task to get it running. The hard part is not installation of tools but writing the docs themselves. johannes
[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
On Thu, Oct 2, 2008 at 03:57, Kalle Sommer Nielsen [EMAIL PROTECTED] wrote: Hi Hannes 2008/10/1 Hannes Magnusson [EMAIL PROTECTED]: 1) cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc 1b) cd phpdoc 2) php configure.php 3) pear channel-discover doc.php.net pear install doc.php.net/phd-beta Actually this isn't always as easy on Windows, mainly because the go-pear seems to not like Windows at all, I still havn't been able to install pear with go-pear. Why not? Getting any errors? I thought it was installed by default by the installer? -Hannes
Re: [PHP-DOC] [DOC] Commit messages dead?
2008/10/1 Greg Beaver [EMAIL PROTECTED]: Elizabeth M Smith wrote: [snip] Many of us - 'documentors' - (if not all) are programmers and used to use CVS and other versioning system. But this takes some extra time that IMHO it shouldn't. If you want to spread the word and get lots of people to help in docs, I believe this kind of thing that Launchpad uses is a go. I'm very well aware that this takes time and not every contributor may actually help with good docs, but it could be moderated. [snip] 100% yes - the initial hurtle to getting new people writing docs is teaching them docbook and cvs. You can whine all you want about how easy it is - but it is NOT a zero learning curve and there are no good (free) docbook tools on the systems most people use on the desktop (yes, I mean Windows - and no people are not going to switch OS's for docbook tools). Writing in XML is not a natural thing. An online interface where people can edit docs would seriously boost people helping out. Why do you think there are so many user notes in the PHP manual ;) However...you will have to wade through the bad docs too. And I have no solution for dealing with the three million tools issues. Hi, I think Hannes was also talking about the fact that committers to CVS are not using [DOC] in their commit messages. I agree with Liz's appraisal of setting up docs for documenting. This could actually be solved with a minimal VMWare appliance that is pre-setup with everything we need to do the docs (not sure how hard that is to do). VMware works great on windows and the version we would need is free. An online interface would be useful, but would it really occur to the developers committing to php's cvs to use it? I'm not so sure. It takes me almost as long, sometimes twice as long to document the things that I write, this is the main problem from a coder's perspective: free time. I would almost rather have short summaries inside /* */ of how things work close to the lines that implement them, it would make it easier to debug other people's code as well as make documenting small changes easier. Big changes perhaps should be documented with either quick README.DOCUMENTING files, or some other quick-and-dirty situation in the source repo for those who are not yet comfortable in docbook, or in English (as both native and non-native speakers can attest, it's hard to translate PHP into English :). This was done with namespaces, and it made documenting easier, right? Greg Hi, I know I'm a small voice here, but try to follow my reasoning. The core devs write C code. The compile C code. They test it. Now, in my mind they are going to be using PHP code to test it (yes?). So, these tests are the best documentation you can get. They show you HOW it works, not from the internals perspective, but from the userland perspective (how do I use this function/method). Having to test it works requires an understanding of how it works. So, MAYBE, the core-devs could write userland code examples. Covering all the methods/parameters. I'm SURE (ahem) they already have this otherwise, how do they know there code works. A few additional comments to the code would help everyone. Not reams like I seem to produce on such a small topic (I'm wordy, get over it). I'm not talking about code coverage or unit tests here, they serve a different function. Knowing how your code will behave with broken data is one thing, but making sure it works with valid data is just as valid test. Is there a way to get just examples for all the functions? If the core-devs tests are good enough to make sure the code works, then it should be good enough for users to work from. Richard. -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498r=213474731 Standing on the shoulders of some very clever giants!
[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
2008/10/2 Hannes Magnusson [EMAIL PROTECTED]: On Thu, Oct 2, 2008 at 03:57, Kalle Sommer Nielsen [EMAIL PROTECTED] wrote: Hi Hannes 2008/10/1 Hannes Magnusson [EMAIL PROTECTED]: 1) cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc 1b) cd phpdoc 2) php configure.php 3) pear channel-discover doc.php.net pear install doc.php.net/phd-beta Actually this isn't always as easy on Windows, mainly because the go-pear seems to not like Windows at all, I still havn't been able to install pear with go-pear. Why not? Getting any errors? I thought it was installed by default by the installer? I do not use the installer, I simply just extra php to the folder I want to use it from. When I use: C:\PHP_5_2\go-pear It asks me to install a system or local wide install, then it comes up with some configuratives where the path to CLI php.exe always is missing. If I press Enter to continue it just shows the same list of paths, if I type all after have configured path 12 (to CLI php.exe), it will end up with this error: 1-12, 'all' or Enter to continue: all Installation base ($prefix) [Inputfejl: Der er ikke noget filtypenavn i C:\Users\Kalle.] : (Input error: There is no filetype name in C:\Users\Kalle) I guess its because the installer doesn't support folders with spaces as the directory is called C:\Users\Kalle Sommer Nielsen\ So you cannot get further or atleast I can't because my username has spaces. I had to edit the phd.bat manually to make it work, not that it was any major but anyway. -Hannes -- Kalle Sommer Nielsen
[PHP-DOC] [DOC] Commit messages dead?
Hi all It looks like [DOC] has failed miserably, it is of no use if only few people use it for few commits. Adding to the fact there is almost no activity in the documentations we really need to find a better way to organize things. Currently we have [DOC], (closed) bug reports, NEWS and wiki all overlapping with each other.. not very attractive for newcomers. Does anyone have any idea how we can organize things better and get more people to document? -Hannes -- Forwarded message -- From: Dmitry Stogov [EMAIL PROTECTED] Date: Wed, Oct 1, 2008 at 15:13 Subject: [PHP-CVS] cvs: php-src(PHP_5_3) / NEWS /ext/soap php_http.c To: [EMAIL PROTECTED] dmitry Wed Oct 1 13:13:34 2008 UTC Modified files: (Branch: PHP_5_3) /php-srcNEWS /php-src/ext/soap php_http.c Log: Added ability to send user defined HTTP headers with SOAP request.
Re: [PHP-DOC] [DOC] Commit messages dead?
On Wed, Oct 1, 2008 at 10:39 AM, Hannes Magnusson [EMAIL PROTECTED] wrote: Hi all It looks like [DOC] has failed miserably, it is of no use if only few people use it for few commits. Adding to the fact there is almost no activity in the documentations we really need to find a better way to organize things. Currently we have [DOC], (closed) bug reports, NEWS and wiki all overlapping with each other.. not very attractive for newcomers. Does anyone have any idea how we can organize things better and get more people to document? -Hannes Well, Not sure how things were around here as I'm kinda new with docs but I might have something. I don't how it works internally neither how it works for new documentation. But I've seen how Ubuntu Launchpad eases the work for translators. Have you seen it? An online interface is much more attractive than this CVS thing. Many of us - 'documentors' - (if not all) are programmers and used to use CVS and other versioning system. But this takes some extra time that IMHO it shouldn't. If you want to spread the word and get lots of people to help in docs, I believe this kind of thing that Launchpad uses is a go. I'm very well aware that this takes time and not every contributor may actually help with good docs, but it could be moderated. The quality of the actual docs is awesome, it's one of the best docs I've ever seen. I don't want to miss that, so I'm all eyes and ears for this thread. Regards, -- Thiago Henrique Pojda
Re: [PHP-DOC] [DOC] Commit messages dead?
[snip] Many of us - 'documentors' - (if not all) are programmers and used to use CVS and other versioning system. But this takes some extra time that IMHO it shouldn't. If you want to spread the word and get lots of people to help in docs, I believe this kind of thing that Launchpad uses is a go. I'm very well aware that this takes time and not every contributor may actually help with good docs, but it could be moderated. [snip] 100% yes - the initial hurtle to getting new people writing docs is teaching them docbook and cvs. You can whine all you want about how easy it is - but it is NOT a zero learning curve and there are no good (free) docbook tools on the systems most people use on the desktop (yes, I mean Windows - and no people are not going to switch OS's for docbook tools). Writing in XML is not a natural thing. An online interface where people can edit docs would seriously boost people helping out. Why do you think there are so many user notes in the PHP manual ;) However...you will have to wade through the bad docs too. And I have no solution for dealing with the three million tools issues. Thanks, Elizabeth Smith
[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
Hannes, I think both Thiago and Elizabeth are correct. Call me old-hat: I prefer CVS but I'm well aware that it's a daunting task to learn that new technology for people who would otherwise not use it. In fact, most projects - including PHP - are moving away from CVS, in favor of SVN, Git, et cetera. If we don't encourage new people to assist in the documentation - and foster them in the process - the docs will suffer. And if the docs suffer, the language is surely going to lose it's position quickly. I propose that the idea of creating a new web-based interface moves forward, and that we put out a call for volunteers to build the new system. I'll even take on the responsibility of leading or co-managing the project, and will donate hardware and bandwidth for the development of the new system. Even to build a system to integrate with the existing one would not be too difficult. Take ideas from the Wiki project, et al, and we can have the results output as XML files if we really want to. The project could be as small as to fill the niche to offer an easy-to-use web interface that uses BBCode-like markup and auto-commits to the CVS repo, or as vast as creating a new, proprietary system. If the proposal from here moves forward, we should set up a convenient time when the initial Working Group can meet on IRC or another medium to set the foundation and iron-out the initial details. -- /Daniel P. Brown More full-root dedicated server packages: Intel 2.4GHz/60GB/512MB/2TB $49.99/mo. Intel 3.06GHz/80GB/1GB/2TB $59.99/mo. Intel 2.4GHz/320/GB/1GB/3TB $74.99/mo. Dedicated servers, VPS, and hosting from $2.50/mo.
Re: [PHP-DOC] [DOC] Commit messages dead?
Elizabeth M Smith wrote: [snip] Many of us - 'documentors' - (if not all) are programmers and used to use CVS and other versioning system. But this takes some extra time that IMHO it shouldn't. If you want to spread the word and get lots of people to help in docs, I believe this kind of thing that Launchpad uses is a go. I'm very well aware that this takes time and not every contributor may actually help with good docs, but it could be moderated. [snip] 100% yes - the initial hurtle to getting new people writing docs is teaching them docbook and cvs. You can whine all you want about how easy it is - but it is NOT a zero learning curve and there are no good (free) docbook tools on the systems most people use on the desktop (yes, I mean Windows - and no people are not going to switch OS's for docbook tools). Writing in XML is not a natural thing. An online interface where people can edit docs would seriously boost people helping out. Why do you think there are so many user notes in the PHP manual ;) However...you will have to wade through the bad docs too. And I have no solution for dealing with the three million tools issues. Hi, I think Hannes was also talking about the fact that committers to CVS are not using [DOC] in their commit messages. I agree with Liz's appraisal of setting up docs for documenting. This could actually be solved with a minimal VMWare appliance that is pre-setup with everything we need to do the docs (not sure how hard that is to do). VMware works great on windows and the version we would need is free. An online interface would be useful, but would it really occur to the developers committing to php's cvs to use it? I'm not so sure. It takes me almost as long, sometimes twice as long to document the things that I write, this is the main problem from a coder's perspective: free time. I would almost rather have short summaries inside /* */ of how things work close to the lines that implement them, it would make it easier to debug other people's code as well as make documenting small changes easier. Big changes perhaps should be documented with either quick README.DOCUMENTING files, or some other quick-and-dirty situation in the source repo for those who are not yet comfortable in docbook, or in English (as both native and non-native speakers can attest, it's hard to translate PHP into English :). This was done with namespaces, and it made documenting easier, right? Greg
Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
On Wed, Oct 1, 2008 at 20:03, Stanislav Malyshev [EMAIL PROTECTED] wrote: On Wed, Oct 1, 2008 at 19:17, Elizabeth M Smith [EMAIL PROTECTED] wrote: tools). Writing in XML is not a natural thing. An online interface where people can edit docs would seriously boost people helping out. Why do you think there are so many user notes in the PHP manual ;) I think a web-based tool that would allow to generate standard docbook pages (at least most primitive ones) and allow to edit certain sections while supporting some basic stuff like paragraphs, links, styles (italic, bold) etc. would be a HUGE help. I can write docbook and have experience with it and I still find it annoying and hard to remember all the details, I can only imagine how intimidating it appears to a newbie. You were extremely unlucky when you wrote the intl docs, sorry for that! :) Now we do however have skeletons for 99% cases, and even a 5minutes tutorial on howto document exceptions[1]. NOTE: Most of the 5minutes are spent explaining how to build the docs. Sure, an online editing tool would be great but I don't think that is a realistic expectation for the time being. I'd rather want PHP5.3 documented before its release then someone spending all their time on weird dirty mixed application that will probably not be ready until PHP6. Why do you think there are so many user notes in the PHP manual ;) Speaking of which, we do also need volunteers to review them. If you login to php.net (via bugsweb or http://master.php.net/manage/users.php) you'll see three boxes above(to the right) of all user notes: 1) Edit (rarely used, mostly just to add ?php ? tags for syntax highlighting if people missed them 2) Reject the note (questions and stuff like that) 3) Delete (wtf notes, bad code/advise, huge code...) _EVERYONE_ with a php.net account can do that and it would be greatly appreciated if people would remove the horror notes when they encounter them. It would even be more appreciated if extension maintainers regularly review the notes attached to their extensions (currently Derick is prettymuch the online who does that). However...you will have to wade through the bad docs too. And I have no solution for dealing with the three million tools issues. I don't understand this argument. All you need for building and view the documentations are 4things: CVS client, PHP, text editor and a browser. All of which you have installed already if you have any interest in PHP at all. To build and view the docs follow these 6steps for the first time, after you follow it once you only have to repeat 3 of the steps 1) cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc 1b) cd phpdoc 2) php configure.php 3) pear channel-discover doc.php.net pear install doc.php.net/phd-beta 4) phd -d .manual.xml -t chunkedhtml 5) firefox html/index.html 6) notepad en/reference/spl/spl/book.xml Now repeat step 2, 4, and 5 after each change you make with you text editor. If you can install PHP on your operating system then you can build the docs and contribute. -Hannes [1] http://doc.php.net/php/dochowto/article.thequicky.exceptions.php
Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
On Wed, Oct 1, 2008 at 21:27, Brandon Savage [EMAIL PROTECTED] wrote: All, I am what I guess you'd call a newbie - Elizabeth got me on this list during ZendCon and though I've been following it I still have no idea how the doc editing process works. I'm exactly who you want this kind of tool for - a new contributor who is eager to contribute but unsure about how to do so. Would you mind being my test-subject then? :) 15minutes of your time (plus couple of minutes to reply back) is all I ask for. Its an easy task: Document the LogicException exception. The exception has no methods (except for inherited once) and how to document exception (from a-z, everything from obtaining the source to building them to actually creating the doc) is already documented at http://doc.php.net/php/dochowto/article.thequicky.exceptions.php If it takes more then 15minutes you can quit and we'll have to try to find better ways. If however you manage to do it in 15minutes or less, please post the file to [EMAIL PROTECTED] -Hannes
Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
I'd be happy to serve as your test subject. I'll post back here when I've done it (sometime this evening once I'm home from the office). Brandon On Wed, Oct 1, 2008 at 4:01 PM, Hannes Magnusson [EMAIL PROTECTED] wrote: On Wed, Oct 1, 2008 at 21:27, Brandon Savage [EMAIL PROTECTED] wrote: All, I am what I guess you'd call a newbie - Elizabeth got me on this list during ZendCon and though I've been following it I still have no idea how the doc editing process works. I'm exactly who you want this kind of tool for - a new contributor who is eager to contribute but unsure about how to do so. Would you mind being my test-subject then? :) 15minutes of your time (plus couple of minutes to reply back) is all I ask for. Its an easy task: Document the LogicException exception. The exception has no methods (except for inherited once) and how to document exception (from a-z, everything from obtaining the source to building them to actually creating the doc) is already documented at http://doc.php.net/php/dochowto/article.thequicky.exceptions.php If it takes more then 15minutes you can quit and we'll have to try to find better ways. If however you manage to do it in 15minutes or less, please post the file to [EMAIL PROTECTED] -Hannes
[PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] [DOC] Commit messages dead?
Hi Hannes 2008/10/1 Hannes Magnusson [EMAIL PROTECTED]: On Wed, Oct 1, 2008 at 20:03, Stanislav Malyshev [EMAIL PROTECTED] wrote: On Wed, Oct 1, 2008 at 19:17, Elizabeth M Smith [EMAIL PROTECTED] wrote: tools). Writing in XML is not a natural thing. An online interface where people can edit docs would seriously boost people helping out. Why do you think there are so many user notes in the PHP manual ;) I think a web-based tool that would allow to generate standard docbook pages (at least most primitive ones) and allow to edit certain sections while supporting some basic stuff like paragraphs, links, styles (italic, bold) etc. would be a HUGE help. I can write docbook and have experience with it and I still find it annoying and hard to remember all the details, I can only imagine how intimidating it appears to a newbie. You were extremely unlucky when you wrote the intl docs, sorry for that! :) Now we do however have skeletons for 99% cases, and even a 5minutes tutorial on howto document exceptions[1]. NOTE: Most of the 5minutes are spent explaining how to build the docs. Sure, an online editing tool would be great but I don't think that is a realistic expectation for the time being. I'd rather want PHP5.3 documented before its release then someone spending all their time on weird dirty mixed application that will probably not be ready until PHP6. Why do you think there are so many user notes in the PHP manual ;) Speaking of which, we do also need volunteers to review them. If you login to php.net (via bugsweb or http://master.php.net/manage/users.php) you'll see three boxes above(to the right) of all user notes: 1) Edit (rarely used, mostly just to add ?php ? tags for syntax highlighting if people missed them 2) Reject the note (questions and stuff like that) 3) Delete (wtf notes, bad code/advise, huge code...) _EVERYONE_ with a php.net account can do that and it would be greatly appreciated if people would remove the horror notes when they encounter them. It would even be more appreciated if extension maintainers regularly review the notes attached to their extensions (currently Derick is prettymuch the online who does that). However...you will have to wade through the bad docs too. And I have no solution for dealing with the three million tools issues. I don't understand this argument. All you need for building and view the documentations are 4things: CVS client, PHP, text editor and a browser. All of which you have installed already if you have any interest in PHP at all. To build and view the docs follow these 6steps for the first time, after you follow it once you only have to repeat 3 of the steps 1) cvs -d:pserver:[EMAIL PROTECTED]/repository co phpdoc 1b) cd phpdoc 2) php configure.php 3) pear channel-discover doc.php.net pear install doc.php.net/phd-beta Actually this isn't always as easy on Windows, mainly because the go-pear seems to not like Windows at all, I still havn't been able to install pear with go-pear. To install PhD I had to manually edit the phd.bat for it to work. 4) phd -d .manual.xml -t chunkedhtml 5) firefox html/index.html 6) notepad en/reference/spl/spl/book.xml Now repeat step 2, 4, and 5 after each change you make with you text editor. If you can install PHP on your operating system then you can build the docs and contribute. -Hannes [1] http://doc.php.net/php/dochowto/article.thequicky.exceptions.php -- PHP Internals - PHP Runtime Development Mailing List To unsubscribe, visit: http://www.php.net/unsub.php -- Kalle Sommer Nielsen
