Re: [PHP-DOC] Re: [PHP-WEBMASTER] [PHP Wiki] new user: antz29
2008/11/26 Lukas Kahwe Smith [EMAIL PROTECTED]: On 26.11.2008, at 09:07, John Le Drew wrote: Hi Lukas I was talking to Steph over the weekend and wanted to put together a set of tutorials + examples for many of the features of PHP, starting with SPL. I thought that the Wiki would be a decent place for these, I also thought about adding them directly to the Docs but I wasn't sure where to start with that; I am familiar with DocBook etc. but not sure who to ask. I was thinking of creating all the pages under /tutorials. You should talk to the doc guys about this. Generally I think they prefer not to use a wiki for this, because they are worried the content will stay there instead of making it to the actual manual. The tool chain for docbook has gotten a lot simpler these days and I am sure they will be very happy to help you out. regards, Lukas Kahwe Smith [EMAIL PROTECTED] Hello John. The usual way to get started is to use CVS to download phpdoc and to get phd (the PHP document builder) via PEAR. Within phpdoc, there is a configure.php script. This essentially combines all the small XML docbook files into one expanded manual (called .manual.xml) phd then can process this file to make HTML, PHP, PDF, etc. You can make alterations to the phpdoc files and run through the configure and build process to test your changes. Then create a few small patches to let us see that you get it. After that, one of the more senior people will give you permission to commit those patches and off you go! Richard. -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498r=213474731 Standing on the shoulders of some very clever giants!
Re: [PHP-DOC] Re: [PHP-WEBMASTER] [PHP Wiki] new user: antz29
Thanks Richard Downloading the docs now :) Where is a decent place to start putting my tutorials? I really wanted to create decent use cases and examples for SPL, as so many people know of it, but have no idea how or why they would implement it. Cheers John 2008/11/26 Richard Quadling [EMAIL PROTECTED]: 2008/11/26 Lukas Kahwe Smith [EMAIL PROTECTED]: On 26.11.2008, at 09:07, John Le Drew wrote: Hi Lukas I was talking to Steph over the weekend and wanted to put together a set of tutorials + examples for many of the features of PHP, starting with SPL. I thought that the Wiki would be a decent place for these, I also thought about adding them directly to the Docs but I wasn't sure where to start with that; I am familiar with DocBook etc. but not sure who to ask. I was thinking of creating all the pages under /tutorials. You should talk to the doc guys about this. Generally I think they prefer not to use a wiki for this, because they are worried the content will stay there instead of making it to the actual manual. The tool chain for docbook has gotten a lot simpler these days and I am sure they will be very happy to help you out. regards, Lukas Kahwe Smith [EMAIL PROTECTED] Hello John. The usual way to get started is to use CVS to download phpdoc and to get phd (the PHP document builder) via PEAR. Within phpdoc, there is a configure.php script. This essentially combines all the small XML docbook files into one expanded manual (called .manual.xml) phd then can process this file to make HTML, PHP, PDF, etc. You can make alterations to the phpdoc files and run through the configure and build process to test your changes. Then create a few small patches to let us see that you get it. After that, one of the more senior people will give you permission to commit those patches and off you go! 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-WEBMASTER] [PHP Wiki] new user: antz29
On 26.11.2008, at 09:07, John Le Drew wrote: Hi Lukas I was talking to Steph over the weekend and wanted to put together a set of tutorials + examples for many of the features of PHP, starting with SPL. I thought that the Wiki would be a decent place for these, I also thought about adding them directly to the Docs but I wasn't sure where to start with that; I am familiar with DocBook etc. but not sure who to ask. I was thinking of creating all the pages under /tutorials. You should talk to the doc guys about this. Generally I think they prefer not to use a wiki for this, because they are worried the content will stay there instead of making it to the actual manual. The tool chain for docbook has gotten a lot simpler these days and I am sure they will be very happy to help you out. regards, Lukas Kahwe Smith [EMAIL PROTECTED]
Re: [PHP-DOC] Re: [PHP-WEBMASTER] [PHP Wiki] new user: antz29
2008/11/26 John Le Drew [EMAIL PROTECTED]: Thanks Richard Downloading the docs now :) Where is a decent place to start putting my tutorials? I really wanted to create decent use cases and examples for SPL, as so many people know of it, but have no idea how or why they would implement it. Cheers John 2008/11/26 Richard Quadling [EMAIL PROTECTED]: 2008/11/26 Lukas Kahwe Smith [EMAIL PROTECTED]: On 26.11.2008, at 09:07, John Le Drew wrote: Hi Lukas I was talking to Steph over the weekend and wanted to put together a set of tutorials + examples for many of the features of PHP, starting with SPL. I thought that the Wiki would be a decent place for these, I also thought about adding them directly to the Docs but I wasn't sure where to start with that; I am familiar with DocBook etc. but not sure who to ask. I was thinking of creating all the pages under /tutorials. You should talk to the doc guys about this. Generally I think they prefer not to use a wiki for this, because they are worried the content will stay there instead of making it to the actual manual. The tool chain for docbook has gotten a lot simpler these days and I am sure they will be very happy to help you out. regards, Lukas Kahwe Smith [EMAIL PROTECTED] Hello John. The usual way to get started is to use CVS to download phpdoc and to get phd (the PHP document builder) via PEAR. Within phpdoc, there is a configure.php script. This essentially combines all the small XML docbook files into one expanded manual (called .manual.xml) phd then can process this file to make HTML, PHP, PDF, etc. You can make alterations to the phpdoc files and run through the configure and build process to test your changes. Then create a few small patches to let us see that you get it. After that, one of the more senior people will give you permission to commit those patches and off you go! Richard. -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498r=213474731 Standing on the shoulders of some very clever giants! Looking at http://docs.php.net/manual/en/book.spl.php and then http://docs.php.net/manual/en/book.image.php You will see there is an examples section all on its own. My preference would be to be able to incorporate the examples in both a general examples page as well as the specific page (for which ever class you are looking at). Maybe allowing links to examples from other pages would be a good feature. We have links to functions, can we link to examples? The examples would need to be named (I think), so a naming convention may be needed. As for tutorials, that may need a separate book entirely. Currently and in the main, the phpdoc is a reference book on functions/classes. There is little in the way of in-depth tutorials. There are many sites out there dealing with that. I would like to see supported tutorials in the documentation. You also have to weigh up the costs of translators translating larger amounts of content. I would start with the examples section first. Others may want to agree/disagree or have other input. Richard. P.S. I'm a very occasional contributor to the dox. Not an editor or anyone with any more rights. -- - Richard Quadling Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498r=213474731 Standing on the shoulders of some very clever giants!
Re: [PHP-DOC] Re: [PHP-WEBMASTER] [PHP Wiki] new user: antz29
On Wed, Nov 26, 2008 at 15:43, Richard Quadling [EMAIL PROTECTED] wrote: Maybe allowing links to examples from other pages would be a good feature. We have links to functions, can we link to examples? The examples would need to be named (I think), so a naming convention may be needed. There is no good way to link to examples in docbook except for xref linkend=the.example.id / or link linkend=the.example.idtext/link. I don't think we need to invent our own example linking tag as in most cases you either want the example actual title as the link (in which case you use xref) or you want to make up your own title (in which case you use link). Adding links to examples from the see also lists (and class reference pages) is obviously a good idea where appropriate. -Hannes
