SPL docs

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" nlopess@php.net
To: "Andrei Zmievski" andrei@gravitonic.com; "Andi Gutmans"
andi@zend.com
Cc: helly@php.net; "Derick Rethans" derick@php.net;
internals@lists.php.net
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 -----

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:

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

--

__________ NOD32 1.1380 (20060125) Information __________

This message was checked by NOD32 antivirus system.
http://www.eset.com

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:

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:

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

Best regards,
Marcus

--

--
Xnyo - http://xnyo.odynia.org/

Hello Steph,

Saturday, June 10, 2006, 12:58:30 PM, you wrote:

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.

Both true, still tht what i use docs most for, looking up stuff again to
be really sure.

Best regards,
Marcus