# SPL docs - Thread: https://externals.io/message/24013 - Original archive: https://news-web.php.net/php.internals/24013 - Started by Andi Gutmans on 2006-06-08T23:25:56+00:00 - Messages: 20 - 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 --- ## #24013 — Andi Gutmans — 2006-06-08T23:25:56+00:00 URL: https://externals.io/message/24013#24013 Hey Marcus, Any chance we can get the SPL docs integrated into the PHP manual? I get questions about it here and there and think that as it's in the default PHP distro it makes sense to have that as part of the official PHP manual. Andi --- ## #24018 — Derick Rethans — 2006-06-09T06:25:23+00:00 URL: https://externals.io/message/24013#24018 · In reply to: #24013 > Any chance we can get the SPL docs integrated into the PHP manual? I > get questions about it here and there and think that as it's in the > default PHP distro it makes sense to have that as part of the official > PHP manual. There is no way we can do that as the docbook stuff's OO support is well, quite minimal. regards, Derick -- Derick Rethans http://derickrethans.nl | http://ez.no | http://xdebug.org --- ## #24020 — Marcus Boerger — 2006-06-09T07:24:14+00:00 URL: https://externals.io/message/24013#24020 · In reply to: #24013 Hello Andi, the problem is the non existing OO support in docbook. I had the idea of eventually using doxygen's xml output and putting that somehow in the manual. But that's is probably something for livedocs. So lets have livedocs first. Apart from that nobody hinders the doc team from copying and translating the stuff from the separate SPL docs to the manual. It is just impossible to integrate the inheritance info and all the graphics to the manual. best regards marcus Friday, June 9, 2006, 1:25:56 AM, you wrote: > Hey Marcus, > Any chance we can get the SPL docs integrated into the PHP manual? I > get questions about it here and there and think that as it's in the > default PHP distro it makes sense to have that as part of the > official PHP manual. > Andi Best regards, Marcus --- ## #24032 — Nuno Lopes — 2006-06-09T12:19:56+00:00 URL: https://externals.io/message/24013#24032 · In reply to: #24020 Yep, it not clear how to document such OO beast in docbook. Also we have few active persons working in the documentation, that aren't enough to catch up all the new features, BC breaks, etc.. We probably would need someone to exclusively work on SPL, which we can't afford ATM. Nuno ----- Original Message ----- > Hello Andi, > > the problem is the non existing OO support in docbook. I had the idea > of eventually using doxygen's xml output and putting that somehow in the > manual. But that's is probably something for livedocs. So lets have > livedocs first. Apart from that nobody hinders the doc team from copying > and translating the stuff from the separate SPL docs to the manual. It is > just impossible to integrate the inheritance info and all the graphics to > the manual. > > best regards > marcus > > > Friday, June 9, 2006, 1:25:56 AM, you wrote: > > > […] > > > […] > > > […] > > > > > Best regards, > Marcus --- ## #24036 — Andi Gutmans — 2006-06-09T13:55:21+00:00 URL: https://externals.io/message/24013#24036 · In reply to: #24018 Maybe we can get a volunteer to improve the docbook? At 11:25 PM 6/8/2006, Derick Rethans wrote: > > > > […] > >There is no way we can do that as the docbook stuff's OO support is >well, quite minimal. > >regards, >Derick > >-- >Derick Rethans >http://derickrethans.nl | http://ez.no | http://xdebug.org --- ## #24037 — Andi Gutmans — 2006-06-09T13:57:12+00:00 URL: https://externals.io/message/24013#24037 · In reply to: #24020 This is a docbook limitation? Couldn't we still find some standard way to write it? most of it is manual stuff ala http://framework.zend.com/manual/en/zend.html? No? Andi At 12:24 AM 6/9/2006, Marcus Boerger wrote: >Hello Andi, > > the problem is the non existing OO support in docbook. I had the idea >of eventually using doxygen's xml output and putting that somehow in the >manual. But that's is probably something for livedocs. So lets have >livedocs first. Apart from that nobody hinders the doc team from copying >and translating the stuff from the separate SPL docs to the manual. It is >just impossible to integrate the inheritance info and all the graphics to >the manual. > >best regards >marcus > > >Friday, June 9, 2006, 1:25:56 AM, you wrote: > > > […] > > > […] > > > […] > > > > >Best regards, > Marcus --- ## #24038 — Hannes Magnusson — 2006-06-09T14:03:11+00:00 URL: https://externals.io/message/24013#24038 · In reply to: #24036 > Maybe we can get a volunteer to improve the docbook? We have, http://code.google.com/soc/php/appinfo.html?csaid=1D6D429391DFBA6F -Hannes > > At 11:25 PM 6/8/2006, Derick Rethans wrote: > > […] --- ## #24045 — Andrei Zmievski — 2006-06-09T16:43:09+00:00 URL: https://externals.io/message/24013#24045 · In reply to: #24036 PHP-GTK has been using modified docbook for its stuff... http://gtk.php.net/manual/en/classtree.php -Andrei > Maybe we can get a volunteer to improve the docbook? > > At 11:25 PM 6/8/2006, Derick Rethans wrote: > > […] --- ## #24054 — Nuno Lopes — 2006-06-09T19:51:32+00:00 URL: https://externals.io/message/24013#24054 · In reply to: #24045 The problem is always maintenance.. I've have some knowledge about DSSSL but none about XSL. In phpdoc we use both, that need to be kept in sync, so that's always complicated to make changes. The best option would be to create a "work-group" to study with docbook creators the best approaches to OOP. Again, the problem is that we don't have any specialist in docbook. We work with recipes/templates, that are in a wiki, which are changed twice in a decade :) Nuno ----- Original Message ----- > PHP-GTK has been using modified docbook for its stuff... > > http://gtk.php.net/manual/en/classtree.php > > -Andrei > > > > > […] --- ## #24055 — Andi Gutmans — 2006-06-09T20:10:37+00:00 URL: https://externals.io/message/24013#24055 · In reply to: #24045 I think that doesn't look too bad. It might not be the Doxygen output, etc.. but for the PHP manual I think it's quite adequate. At 09:43 AM 6/9/2006, Andrei Zmievski wrote: >PHP-GTK has been using modified docbook for its stuff... > >http://gtk.php.net/manual/en/classtree.php > >-Andrei > > > > > […] --- ## #24056 — Steph Fox — 2006-06-09T20:14:20+00:00 URL: https://externals.io/message/24013#24056 · In reply to: #24054 Hi Nuno, Christian Weiske and myself have both done quite a lot with docbook - mostly extending the PHP-GTK dtd and forcing the (fairly elderly but much-altered) stylesheets to do all sorts of horrible things they weren't designed to do :). The same goes for James Moore if he's around at all, and of course Goba (if he's around, ditto). I don't know how much any of us (other than Goba) could sensibly be called 'specialist', but we've a fair idea of how it all works between us. Talking with Sebastian and Marcus about their plans a couple of weeks ago, though, I came away with the distinct impression that a docbook-centred solution wasn't what they're hoping for. I think it would be a smart move to agree on the kind(s) of documentation that will be acceptable for PHP OO before we start trying to actually work with other groups to create it. (And probably not on the internals list, those poor inboxes have had their fill of mail from me today.) - Steph ----- Original Message ----- From: "Nuno Lopes" To: "Andrei Zmievski" ; "Andi Gutmans" Cc: ; "Derick Rethans" ; Sent: Friday, June 09, 2006 9:51 PM Subject: Re: [PHP-DEV] SPL docs > The problem is always maintenance.. I've have some knowledge about DSSSL > but none about XSL. In phpdoc we use both, that need to be kept in sync, > so that's always complicated to make changes. > The best option would be to create a "work-group" to study with docbook > creators the best approaches to OOP. Again, the problem is that we don't > have any specialist in docbook. We work with recipes/templates, that are > in a wiki, which are changed twice in a decade :) > > Nuno > > > ----- Original Message ----- > > […] > > -- > > > > > __________ NOD32 1.1380 (20060125) Information __________ > > This message was checked by NOD32 antivirus system. > http://www.eset.com --- ## #24057 — Andi Gutmans — 2006-06-09T20:25:46+00:00 URL: https://externals.io/message/24013#24057 · In reply to: #24056 Hey, I'm obviously not an expert on this stuff so I don't have much added value to add. However, I think from a high-level I think it's important that we have one PHP manual and that the manual covers both functional and oo extensions. I think the last thing we want is to have several PHP manuals. My $.02. Now I'll shut up :) Andi At 01:14 PM 6/9/2006, Steph Fox wrote: >Hi Nuno, > >Christian Weiske and myself have both done quite a lot with docbook >- mostly extending the PHP-GTK dtd and forcing the (fairly elderly >but much-altered) stylesheets to do all sorts of horrible things >they weren't designed to do :). The same goes for James Moore if >he's around at all, and of course Goba (if he's around, ditto). I >don't know how much any of us (other than Goba) could sensibly be >called 'specialist', but we've a fair idea of how it all works between us. > >Talking with Sebastian and Marcus about their plans a couple of >weeks ago, though, I came away with the distinct impression that a >docbook-centred solution wasn't what they're hoping for. I think it >would be a smart move to agree on the kind(s) of documentation that >will be acceptable for PHP OO before we start trying to actually >work with other groups to create it. (And probably not on the >internals list, those poor inboxes have had their fill of mail from me today.) > >- Steph > > >----- Original Message ----- From: "Nuno Lopes" >To: "Andrei Zmievski" ; "Andi Gutmans" >Cc: ; "Derick Rethans" ; > >Sent: Friday, June 09, 2006 9:51 PM >Subject: Re: [PHP-DEV] SPL docs > > > > […] --- ## #24058 — Lukas Smith — 2006-06-09T21:52:13+00:00 URL: https://externals.io/message/24013#24058 · In reply to: #24057 Andi Gutmans wrote: > Hey, > > I'm obviously not an expert on this stuff so I don't have much added > value to add. However, I think from a high-level I think it's important > that we have one PHP manual and that the manual covers both functional > and oo extensions. I think the last thing we want is to have several PHP > manuals. > My $.02. Now I'll shut up :) Well PEAR is far from being able to claim that it has solved its documentation problems. However I generally think that its ok to have different tools for API documentation and end user "tutorial" style documentation. However I guess the main stumbling block is that the PEAR API documentation is currently generated directly from the source which does not really lend itself well for translations. It also means that we have documentation for every single version ever released. However at least I have not been good about noting when features have been added. Also doxygen produces much nicer inheritance graphs than what we currently have. regards, Lukas --- ## #24060 — Andi Gutmans — 2006-06-09T22:18:43+00:00 URL: https://externals.io/message/24013#24060 · In reply to: #24058 Yeah API docs is useful, but still we should have the end-user docs in the PHP manual. I don't think once comes instead of the other. The end-user docs is especially useful as people in the community can give comments, etc... At 02:52 PM 6/9/2006, Lukas Smith wrote: >Andi Gutmans wrote: > > […] > >Well PEAR is far from being able to claim that it has solved its >documentation problems. However I generally think that its ok to >have different tools for API documentation and end user "tutorial" >style documentation. However I guess the main stumbling block is >that the PEAR API documentation is currently generated directly from >the source which does not really lend itself well for translations. >It also means that we have documentation for every single version >ever released. However at least I have not been good about noting >when features have been added. Also doxygen produces much nicer >inheritance graphs than what we currently have. > >regards, >Lukas --- ## #24061 — Lukas Smith — 2006-06-09T22:21:30+00:00 URL: https://externals.io/message/24013#24061 · In reply to: #24060 Andi Gutmans wrote: > Yeah API docs is useful, but still we should have the end-user docs in > the PHP manual. I don't think once comes instead of the other. The > end-user docs is especially useful as people in the community can give > comments, etc... Err, you misunderstood what I was trying to say. All I was saying that we are generating API docs automatically from the phpdoc comments and providing end user docs separately (which gets translated) written in docbook that can of course link to the API docs. regards, Lukas --- ## #24066 — Marcus Boerger — 2006-06-09T23:52:05+00:00 URL: https://externals.io/message/24013#24066 · In reply to: #24037 Hello Andi, that's nothing more than our manual besides a different layout. I'd like to document how studd is being integrated, how stuff works together and how inheritance trees look like. You saw the gtk tree, wow, cool if there is only one real tree like inheritance graph. But unfortunatley SPL has a great amount of interfaces floating around. Intrgrating that and hving all that information revealed is a great problem. I use the docu myself so maybe i am looking from another level but i am not willing to give that level away. I'd rather change the toolset, only the toolchain i can change is doxygen. best regards marcus Friday, June 9, 2006, 3:57:12 PM, you wrote: > This is a docbook limitation? Couldn't we still find some standard > way to write it? most of it is manual stuff ala > http://framework.zend.com/manual/en/zend.html? > No? > Andi > At 12:24 AM 6/9/2006, Marcus Boerger wrote: > > […] Best regards, Marcus --- ## #24067 — Rasmus Lerdorf — 2006-06-09T23:57:28+00:00 URL: https://externals.io/message/24013#24067 · In reply to: #24066 I find the Doxygen-generated SPL docs maze-like and pretty much impossible to navigate. There is nothing stopping you from maintaining that separate document, but I'd love to see the useful bits integrated into the PHP docs. Losing the inheritance graphs doesn't bother me a bit. -Rasmus Marcus Boerger wrote: > Hello Andi, > > that's nothing more than our manual besides a different layout. I'd > like to document how studd is being integrated, how stuff works together > and how inheritance trees look like. You saw the gtk tree, wow, cool if > there is only one real tree like inheritance graph. But unfortunatley > SPL has a great amount of interfaces floating around. Intrgrating that > and hving all that information revealed is a great problem. I use the > docu myself so maybe i am looking from another level but i am not > willing to give that level away. I'd rather change the toolset, only the > toolchain i can change is doxygen. > > best regards > marcus > > Friday, June 9, 2006, 3:57:12 PM, you wrote: > > > […] > > > > […] > > > > > Best regards, > Marcus --- ## #24070 — Robert Amos — 2006-06-10T01:47:39+00:00 URL: https://externals.io/message/24013#24070 · In reply to: #24067 I agree with Rasmus here, there should be at least some level of the docs in the PHP manual. Its always been considered the "one stop shop" for reference for all the beginning coders that I've seen, and is one of the draws for the language. Having a seperate set of docs for the more "advanced" information about SPL is fine too. -bok > > I find the Doxygen-generated SPL docs maze-like and pretty much > impossible to navigate. There is nothing stopping you from maintaining > that separate document, but I'd love to see the useful bits integrated > into the PHP docs. Losing the inheritance graphs doesn't bother me a bit. > > -Rasmus > > Marcus Boerger wrote: > > […] > idea > > […] > the > > […] > copying > > […] > is > > […] > to > > […] > > -- > > > > -- Xnyo - http://xnyo.odynia.org/ --- ## #24073 — Steph Fox — 2006-06-10T10:58:30+00:00 URL: https://externals.io/message/24013#24073 · In reply to: #24066 Hi Marcus > that's nothing more than our manual besides a different layout. I'd > like to document how studd is being integrated, how stuff works together > and how inheritance trees look like. You saw the gtk tree, wow, cool if > there is only one real tree like inheritance graph. But unfortunatley > SPL has a great amount of interfaces floating around. Intrgrating that > and hving all that information revealed is a great problem. I use the > docu myself so maybe i am looking from another level but i am not > willing to give that level away. I'd rather change the toolset, only the > toolchain i can change is doxygen. Yep, we're about to hit similar issues over documenting interfaces in PHP-GTK... at present they're more or less treated as classes. I really don't want to throw away the entire php-gtk-doc structure just to deal with those though :) and I'd imagine nobody wants to throw out the otherwise solid phpdoc structure either. I have to say also that I don't find doxygen-generated documentation intuitive. It's more useful if you already know about something and need to look up some detail than it is if you're trying to learn how that thing works in the first place. - Steph --- ## #24074 — Marcus Boerger — 2006-06-10T11:22:15+00:00 URL: https://externals.io/message/24013#24074 · In reply to: #24073 Hello Steph, Saturday, June 10, 2006, 12:58:30 PM, you wrote: > Hi Marcus > > […] > Yep, we're about to hit similar issues over documenting interfaces in > PHP-GTK... at present they're more or less treated as classes. I really > don't want to throw away the entire php-gtk-doc structure just to deal with > those though :) and I'd imagine nobody wants to throw out the otherwise > solid phpdoc structure either. > I have to say also that I don't find doxygen-generated documentation > intuitive. It's more useful if you already know about something and need to > look up some detail than it is if you're trying to learn how that thing > works in the first place. Both true, still tht what i use docs most for, looking up stuff again to be really sure. Best regards, Marcus