On 8/21/07, Dan Scott <[EMAIL PROTECTED]> wrote: > On 20/08/07, M. Sokolewicz <[EMAIL PROTECTED]> wrote: > > Hannes Magnusson wrote: > > > On 8/20/07, Stanislav Malyshev <[EMAIL PROTECTED]> wrote: > > >> Hi! > > >> > > >> In the intl extension documentation, we already have now quite a lot of > > >> contents on the reference page and expect to have more - right now we > > >> have 2 classes each to have 10+ methods and constants, and soon there > > >> will be 3-4 more classes. I am thinking about putting class descriptions > > >> into separate pages to keep reference page readable. > > >> However, I'm not sure what's the right way to do it. I tried to put > > >> classes inside <refentry> block, which did render it as a separate page > > >> but the link to it not appears at the "links" part and not in the > > >> "Predefined classes" part. Also, I'm not sure how to handle the > > >> constants. Any advice? > > > > > > You are asking a lot of uncomfortable questions. > > > OO docs are a complete and total mess currently and you have my full > > > sympathy. > > > > > > The pecl/http is currently "almost a skeleton" for new OO extensions, > > > so you should probably steal ideas there. > > > > > > As you can see looking at > > > http://php.net/manual/en/http.HttpMessage.php & > > > http://php.net/manual/en/imagick.imagick.php this "skeleton" is > > > totally not working out, but its the best we got at the moment. > > > > > > In all honesty, if you could I'd recommend you to wait for a week, or > > > two, probably three..., with these docs. We really need to work on a > > > real skeleton for OO docs but for that to happen we need render > > > implementation for it. > > > Until then, the best I can advice you is to follow Mikes footsteps > > > with his pecl/http docs. > > > > > > FYI; The short-term-plan for the new OO skel is that each class acts > > > like a reference page, and the toc on the left only listing the > > > methods in that class (not all 1000 methods in that extension). So, > > > you are on the right track with wanting to split the class > > > descriptions into separate pages. > > > Also, *when* the "new OO skel" will be ready, I will try to "convert" > > > the old docs to it myself so you don't really need to worry too much > > > about... > > > > > > -Hannes > > > > So we'll finally get rid of that horrid PDO... clog...? (the ref page is > > horrid, huge and impossible to navigate easily) > > > > Hey, don't hold back, tell us how you _really_ feel! > > But seriously -- if you felt the PDO reference page was that bad all > this time, have you offered any suggestions in the past for how to > improve it?
Its not about PDO. Have you seen the SDO docs? Its freakin gigantic. Its not about SDO either :) Its no ones fault really. Our templates just suck (for these kind of extensions) and people are trying the best they can working around it. We have been kicking around the idea, on IRC, of making each extension "a book", i.e. having tutorial, faq, best practices and lot of other info for each and every extension. Its kinda unrealistic goal, but I think it is worth the consideration at least. The main issue here is the utter lack of a decent skeleton/template for huge/OO extensions. The chunking rules for <reference>s in Docbook are the biggest problem there, so until we can come up with a implementation, for custom chunking, reference pages will continue to suck and people will try to work around any way they can. As we are (hopefully) dropping Docbook-xsl and dsssl asap I don't think it is worth it if someones patches it. Our focus should be on getting PhD stable and then implement some neat tricks for a new OO skeleton. I am crazy busy this week so I don't have the time to do anything about this, but as soon as I can I will post an idea for a skeleton and, if people like it, patch phd for it. -Hannes
