Re: Fwd: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
> > Hey, Gabor and David -- thanks for the interest -- here's what I sent > > to Nuno earlier today. That looks pretty good. One thing that sprung to mind is that you don't mention much about Windows tools, but you do give examples of Linux tools. I don't know what the common platform is, but I use Windows. My tool of choice is obviously Cygwin for source management, but also Jedit for the actual editing of the docs. Might be worth mentioning? -- Regards, David Mytton http://www.olate.co.uk
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
Sure, I'd like to take a look! On 4/27/05, Dan Scott <[EMAIL PROTECTED]> wrote: > If anyone on the list is interested in reviewing the presentation, let > me know and I'll forward it to you in its current state. (Marco, if > you're reading this -- it'll be done soon, I promise!) > > Dan > -- Regards, David Mytton http://www.olate.co.uk
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
On 4/15/05, David Mytton <[EMAIL PROTECTED]> wrote: > On 4/15/05, Dan Scott <[EMAIL PROTECTED]> wrote: > > I'm on the hook to put together a presentation on the same topic for > > php|tropics over the next couple of days, so perhaps we can review > > each other's work? > > > > (I hear you on the busy-ness side of things) > > > > Dan > > > > Yeh, sounds good. My plan is to provide a numbered step by step guide > on how to get into helping with the PHP documentation along with some > common problems and FAQs. My idea is that it is brief, but concise > with any elaboration done by linking to the documentation already > there. I haven't started as yet, have you got anything? > -- > Regards, > > David Mytton > http://www.olate.co.uk > David, Gabor, et al: I've got a rough presentation pulled together, which covers most of the points I want to talk about. Still need to flesh some of it out (particularly the mini-primer to DocBook) but the shape of it feels just about right. If anyone on the list is interested in reviewing the presentation, let me know and I'll forward it to you in its current state. (Marco, if you're reading this -- it'll be done soon, I promise!) Dan
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
On 4/15/05, Dan Scott <[EMAIL PROTECTED]> wrote: > I'm on the hook to put together a presentation on the same topic for > php|tropics over the next couple of days, so perhaps we can review > each other's work? > > (I hear you on the busy-ness side of things) > > Dan > Yeh, sounds good. My plan is to provide a numbered step by step guide on how to get into helping with the PHP documentation along with some common problems and FAQs. My idea is that it is brief, but concise with any elaboration done by linking to the documentation already there. I haven't started as yet, have you got anything? -- Regards, David Mytton http://www.olate.co.uk
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
I'm on the hook to put together a presentation on the same topic for php|tropics over the next couple of days, so perhaps we can review each other's work? (I hear you on the busy-ness side of things) Dan, you will most certainly find help around here, since we are also in need of more input for the howto anyway :) And even more input for the docs for that matter. Goba
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
On 4/15/05, David Mytton <[EMAIL PROTECTED]> wrote: > On 4/6/05, David Mytton <[EMAIL PROTECTED]> wrote: > > Since I recently started working on the docs, do you think it is worth > > me writing a quick start document with bullet points explaining > > exactly how to get involved (referencing pages in the howto)? When I > > originally looked at it, I found the howto very in depth and not that > > great for beginners. > > Well I was going to do this last week, but I have been stupidly busy > so haven't gotten around to it. Maybe this next week won't be so busy > :( > -- > Regards, > > David Mytton > http://www.olate.co.uk David: I'm on the hook to put together a presentation on the same topic for php|tropics over the next couple of days, so perhaps we can review each other's work? (I hear you on the busy-ness side of things) Dan
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
On 4/6/05, David Mytton <[EMAIL PROTECTED]> wrote: > Since I recently started working on the docs, do you think it is worth > me writing a quick start document with bullet points explaining > exactly how to get involved (referencing pages in the howto)? When I > originally looked at it, I found the howto very in depth and not that > great for beginners. Well I was going to do this last week, but I have been stupidly busy so haven't gotten around to it. Maybe this next week won't be so busy :( -- Regards, David Mytton http://www.olate.co.uk
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
On Apr 6, 2005 6:18 PM, Philip Olson <[EMAIL PROTECTED]> wrote: > Have you looked at the README? Yes, I have. -- Regards, David Mytton http://www.olate.co.uk
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
> On Apr 6, 2005 4:14 PM, Gabor Hojtsy <[EMAIL PROTECTED]> wrote: > > A quick start guide would be nice at the start of the howto, which links > > to detailed information in the document. > > > > Goba > > > > Ok, I'll write something up either today or tomorrow. Have you looked at the README? Regards, Philip
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
On Apr 6, 2005 4:14 PM, Gabor Hojtsy <[EMAIL PROTECTED]> wrote: > A quick start guide would be nice at the start of the howto, which links > to detailed information in the document. > > Goba > Ok, I'll write something up either today or tomorrow. -- Regards, David Mytton http://www.olate.co.uk
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
Since I recently started working on the docs, do you think it is worth me writing a quick start document with bullet points explaining exactly how to get involved (referencing pages in the howto)? When I originally looked at it, I found the howto very in depth and not that great for beginners. A quick start guide would be nice at the start of the howto, which links to detailed information in the document. Goba
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
Since I recently started working on the docs, do you think it is worth me writing a quick start document with bullet points explaining exactly how to get involved (referencing pages in the howto)? When I originally looked at it, I found the howto very in depth and not that great for beginners. -- Regards, David Mytton http://www.olate.co.uk
Re: [PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
1) I don't know how to update the HOWTO on php.net andthis was brought up once, summary: wait for docweb 2) Nobody knows when the upcoming phpdocweb site, codenamed "docweb", will be online. It however is where the updated php doc HOWTO will eventually always live. * http://doc.php.net/php/dochowto/ IMHO the doc howto at doc.php.net is supposed to be up to date. If not, it should be added to the cronjobs. If this is handled, the dochowto at php.net should be removed completely, and a redirection should be put in place to the doc site. Doc.php.net also should host a howto download file somewhere for those, who have modem access, so they can get the howto for offline browsing. Now that http://doc.php.net/php/dochowto/ updates weekly and given the fact that we don't propose a downloadable format for the howto on www.php.net, why don't we switch the URLs ? OK, just removed the howto copy bit from the cronjob. I was unable to find, where it gets generated after all, since the mirror targets in phpdoc does not include the howto, while it somehow should get generated, as otherwise it would not be copied. I also disabled the revcheck generation code on the build machine, so revchecks will also disapear from the mirror sites after the next builds. Doc.php.net is now the place to go for these stuff. Goba
[PHP-DOC] Switching the howto to doc.php.net (was Re: [PHP-DOC] Contributing)
Gabor Hojtsy wrote: >> 1) I don't know how to update the HOWTO on php.net andthis was >> brought up once, summary: wait for docweb >> 2) Nobody knows when the upcoming phpdocweb site, codenamed >>"docweb", will be online. It however is where the >>updated php doc HOWTO will eventually always live. >>* http://doc.php.net/php/dochowto/ > > > IMHO the doc howto at doc.php.net is supposed to be up to date. If not, > it should be added to the cronjobs. If this is handled, the dochowto at > php.net should be removed completely, and a redirection should be put in > place to the doc site. Doc.php.net also should host a howto download > file somewhere for those, who have modem access, so they can get the > howto for offline browsing. Now that http://doc.php.net/php/dochowto/ updates weekly and given the fact that we don't propose a downloadable format for the howto on www.php.net, why don't we switch the URLs ? Mehdi
Re: [PHP-DOC] Contributing
Hi Philip, Goba, Sean > Also in this perfect world docweb will have all the > information phpdoc.info has. So we'll wait until this perfect world becomes true ;-) Thanks for your clarification. It is better to not wait but participate if possible :) It will not come, if too many people go on the wait side... Goba
Re: [PHP-DOC] Contributing
Hi Philip, Goba, Sean > Also in this perfect world docweb will have all the > information phpdoc.info has. So we'll wait until this perfect world becomes true ;-) Thanks for your clarification. Regards Conni
Re: [PHP-DOC] Contributing
Gabor Hojtsy wrote: Yes, it would definitely be better. I can hand out CVS write access to those, who are willing to contribute to the doc.php.net website, which is supposed to be this very place. The doc website team has a mailing list, but sadly only a few people are active. http://news.php.net/php.doc.web Since I'm new I'll be going through the process described in the doc website at the moment so I could help out by adding to it in places I get stuck. Perhaps a FAQ might be appropriate because I asked a couple of questions on this list and in IRC last night which weren't answered in the howto. But I don't have a CVS account yet (I have e-mailed group@). My first thoughts when looking at it was that there is a lot of info there and some of it is quite complex. It might be worth adding a 'First Steps' page which has a numbered list of very brief instructions about how to get started. That could be the first thing to read for new people which explains what to do next and could link to the other pages which describe everything in more detail. David
Re: [PHP-DOC] Contributing
What fun would that be? ;) 1) I don't know how to update the HOWTO on php.net and this was brought up once, summary: wait for docweb 2) Nobody knows when the upcoming phpdocweb site, codenamed "docweb", will be online. It however is where the updated php doc HOWTO will eventually always live. * http://doc.php.net/php/dochowto/ IMHO the doc howto at doc.php.net is supposed to be up to date. If not, it should be added to the cronjobs. If this is handled, the dochowto at php.net should be removed completely, and a redirection should be put in place to the doc site. Doc.php.net also should host a howto download file somewhere for those, who have modem access, so they can get the howto for offline browsing. 3) The phpdoc.info site is a site maintained by some members of phpdoc and is not an official php.net project. It's a quick fix (and a nice one IMHO) to getting the job done. So in a perfect world docweb will be finished and the updated HOWTO will live there but this has not happened yet. Also in this perfect world docweb will have all the information phpdoc.info has. And the only way to make this happen is to have more people on board improving doc.php.net, for which I can give out CVS Karma to those interested (given you already have a CVS account). That site is supposed to be as broad as covering all php.net documentation projects, including PEAR and PECL, since we use very similar tools (based on docbook, and command line tools), and face very similar problems and issues. So the willingness is absolutely there to make a central documentation resource site for those interested, but the "human resources" are not there yet. Goba
Re: [PHP-DOC] Contributing
Hi Cornelia, It is somehow confusing ... Two days (?) ago there was an advice to go to http://wiki.phpdoc.info/DocSkel because the HOWTO is somewhat outdated. Now the advice to use the HOWTO at either php.net/dochowto or http://doc.php.net/php/dochowto/index.php ... Why is important stuff spread on different websites and which one contains the latest versions? In my opinion this doesn't make things easier. Especially for new people. Wouldn't it be better to put all doc-related stuff on one place. I think maintaining three sites is more effort than keeping track on one ;-) Yes, it would definitely be better. I can hand out CVS write access to those, who are willing to contribute to the doc.php.net website, which is supposed to be this very place. The doc website team has a mailing list, but sadly only a few people are active. http://news.php.net/php.doc.web BTW, I don't understand what this means: http://wiki.phpdoc.info/DocSkel/MigrationStatus?v=d8i When migrating a reference, please separate your CVS commits : * a commit for whitespaces (remember that the new docs starts at col 0) * a commit for the actual migration It is easier to human-review a file, if it only contains actual changes (no whitespace changes). Whitespace changes will surely be dismissed by those, who are keen on looking out what was changed, actual changes are sometimes reviewed. Goba
Re: [PHP-DOC] Contributing
Conni, You are correct. It is confusing. We're making an effort to centralize phpdoc (&& peardoc && smartydoc && php-gtk-doc && etc), into one place: docweb (see the docweb mailing list, or http://doc.php.net/). This process has proven slow. Mostly because the contributors have been very busy recently, and haven't done much.. uh.. contributing. phpdoc.info is my domain, and I run the sites hosted there. It's a temporary solution to a permanent problem. The permanent solution will be docweb. phpdoc.info is somewhat useful, but always unofficial. S Cornelia Boenigk wrote: Hi All It is somehow confusing ... Two days (?) ago there was an advice to go to http://wiki.phpdoc.info/DocSkel because the HOWTO is somewhat outdated. Now the advice to use the HOWTO at either php.net/dochowto or http://doc.php.net/php/dochowto/index.php ... Why is important stuff spread on different websites and which one contains the latest versions? In my opinion this doesn't make things easier. Especially for new people. Wouldn't it be better to put all doc-related stuff on one place. I think maintaining three sites is more effort than keeping track on one ;-) Regards Conni BTW, I don't understand what this means: http://wiki.phpdoc.info/DocSkel/MigrationStatus?v=d8i When migrating a reference, please separate your CVS commits : * a commit for whitespaces (remember that the new docs starts at col 0) * a commit for the actual migration
Re: [PHP-DOC] Contributing
> It is somehow confusing ... Yes, this is expected at this stage of phpdoc. > Two days (?) ago there was an advice to go to > http://wiki.phpdoc.info/DocSkel because the HOWTO is somewhat > outdated. Now the advice to use the HOWTO at either php.net/dochowto > or http://doc.php.net/php/dochowto/index.php ... > > Why is important stuff spread on different websites and which one > contains the latest versions? In my opinion this doesn't make things > easier. Especially for new people. > > Wouldn't it be better to put all doc-related stuff on one place. I > think maintaining three sites is more effort than keeping track on one ;-) What fun would that be? But seriously, I'll be as blunt as possible so here's how I see it: 1) I don't know how to update the HOWTO on php.net and this was brought up once, summary: wait for docweb 2) Nobody knows when the upcoming phpdocweb site, codenamed "docweb", will be online. It however is where the updated php doc HOWTO will eventually always live. * http://doc.php.net/php/dochowto/ 3) The phpdoc.info site is a site maintained by some members of phpdoc and is not an official php.net project. It's a quick fix (and a nice one IMHO) to getting the job done. So in a perfect world docweb will be finished and the updated HOWTO will live there but this has not happened yet. Also in this perfect world docweb will have all the information phpdoc.info has. > BTW, I don't understand what this means: > http://wiki.phpdoc.info/DocSkel/MigrationStatus?v=d8i > > When migrating a reference, please separate your CVS commits : > > * a commit for whitespaces (remember that the new docs starts at > col 0) > * a commit for the actual migration Compare the old style with the new style. Notice the old style all begins on column 2 (not flush left) while the new style starts at column 0 (flush left). I believe this extra whitespace got inserted when the manual had a huge banana split but anyway now you know. Do not mix whitespace changes with content changes...that's the point. I'll add some clarity to that Wiki now. Regards, Philip
Re: [PHP-DOC] Contributing
Where should I be heading then to get the right tools setup so I can check that I've done everything ok? I'm using Windows as my primary system. David Cornelia Boenigk wrote: Hi All It is somehow confusing ... Two days (?) ago there was an advice to go to http://wiki.phpdoc.info/DocSkel because the HOWTO is somewhat outdated. Now the advice to use the HOWTO at either php.net/dochowto or http://doc.php.net/php/dochowto/index.php ... Why is important stuff spread on different websites and which one contains the latest versions? In my opinion this doesn't make things easier. Especially for new people. Wouldn't it be better to put all doc-related stuff on one place. I think maintaining three sites is more effort than keeping track on one ;-) Regards Conni BTW, I don't understand what this means: http://wiki.phpdoc.info/DocSkel/MigrationStatus?v=d8i When migrating a reference, please separate your CVS commits : * a commit for whitespaces (remember that the new docs starts at col 0) * a commit for the actual migration
Re: [PHP-DOC] Contributing
Hi All It is somehow confusing ... Two days (?) ago there was an advice to go to http://wiki.phpdoc.info/DocSkel because the HOWTO is somewhat outdated. Now the advice to use the HOWTO at either php.net/dochowto or http://doc.php.net/php/dochowto/index.php ... Why is important stuff spread on different websites and which one contains the latest versions? In my opinion this doesn't make things easier. Especially for new people. Wouldn't it be better to put all doc-related stuff on one place. I think maintaining three sites is more effort than keeping track on one ;-) Regards Conni BTW, I don't understand what this means: http://wiki.phpdoc.info/DocSkel/MigrationStatus?v=d8i When migrating a reference, please separate your CVS commits : * a commit for whitespaces (remember that the new docs starts at col 0) * a commit for the actual migration
Re: [PHP-DOC] Contributing
Read the fine howto: php.net/dochowto to make yourself somewhat familiar with the tools we use. Correct spelling errors, rewrite parts of the docs, solve doc bugs (bugs.php.net) etc. Yeah, I have been reading through that and will get started on it right away. I'll also go ahead and apply for a CVS account. David
Re: [PHP-DOC] Contributing
Hi, I am interested in contributing to the PHP Documentation. I have been using PHP for 2 years or so now, and would like to help out where ever possible. I e-mailed the PHP Internals list and they recommended that I post to the documentation list. How should I go about getting involved? Read the fine howto: php.net/dochowto to make yourself somewhat familiar with the tools we use. Correct spelling errors, rewrite parts of the docs, solve doc bugs (bugs.php.net) etc. Friedhelm
Re: [PHP-DOC] Contributing
Hi David, I am interested in contributing to the PHP Documentation. I have been using PHP for 2 years or so now, and would like to help out where ever possible. I e-mailed the PHP Internals list and they recommended that I post to the documentation list. How should I go about getting involved? We have a documentation howto, which outlines the processes and tools used in the documentation process. Check out: http://doc.php.net/php/dochowto/index.php Feel free to ask questions, or if you have any ideas on where could you help the project, explain your ideas. Goba
Re: [PHP-DOC] Contributing
I am interested in contributing to the PHP Documentation. I have been using PHP for 2 years or so now, and would like to help out where ever possible. I e-mailed the PHP Internals list and they recommended that I post to the documentation list. How should I go about getting involved? You need to checkout the phpdoc CVS module, and perhaps get it to the stage where you can build the docs yourself. That way you can make changes, test them and submit them for inclusion. Chris
[PHP-DOC] Contributing
Hi, I am interested in contributing to the PHP Documentation. I have been using PHP for 2 years or so now, and would like to help out where ever possible. I e-mailed the PHP Internals list and they recommended that I post to the documentation list. How should I go about getting involved? David Mytton
