On 21/08/07, M. Sokolewicz <[EMAIL PROTECTED]> wrote: > Dan Scott 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? > > > > Is it any wonder that people lose interest in contributing to a > > project subject to so much criticism and so little positive feedback? > > > > Sheesh. > > > > For what it's worth, the PDO reference page is the result of taking > > the existing OO doc approach and trying to include an introductory > > tutorial within the only logical spot. Overall, the bulk of the > > current PHP manual is structured as a reference manual, and doesn't > > lend itself to tutorial-type information. Perhaps the tutorial / > > extended introduction material could be moved into a new "Tutorials" > > section (I'm avoiding the "Appendices" section because that's a > > meaningless catch-all term, and "Features" is debatable -- come to > > think of it, should "Safe Mode" still be classified as a feature? > > Probably better to stuff it into the appendices...). Combine that with > > the new direction for OO docs (per-class? +1 from me! and I'm assuming > > a separate page for the lengthy list of constants as well) and I think > > that will address most of the current problems. > > > > Actually Dan, I did write a quite long message about my suggestions on > the PDO page quite a while ago which sparked some discussion about > splitting off parts and recombining it in a different way.
Maybe on some other list, or under some other name? A search for "Sokolewicz PDO" or "tularis PDO" didn't result in any hits in my list archives before I sent my previous email, and I've been subscribed to php-doc since 2004. But maybe I somehow missed it. Just to > repeat what I said back then: > It's simply too long, and impossible to quickly browse trough. What I > suggested back then was to: > 1. split off the constants to a separate page Agreed. That's what I said in my previous message. > 2. get rid of the whole installation bit (as it's the same for pretty > much any extension) or at least move it to a separate page aswell Move it to a separate page. There were a lot of people running into problems with the SQLite vs. PDO issue, if I recall correctly, which is why the whole "building as a shared extension" section is the way it is. > 3. 1 example is fine to show the "power" of the extension, but the > examples on the PDO refpage serve a completely different purpose: they > show how the extension should be used and explain a ton of features, all > of which is not what (imo) the ref page was meant for. This would be what I meant by a "tutorial" in my previous message. So do you agree it should be moved into a new "Tutorials" section? I think most of the SDO ref page would fit nicely as a self-contained tutorial as well. > Now, I know how it all came to exist, I've been on the list for a > loooong time, and I can say I was really glad to see how people managed > to fit it into the framework we had back then (and mostly still have > now). Unfortunately it grew in a direction that was (as later became > apparent) not quite the "best". I'd just like to repeat, though it was > good at first and I really do think it was, it's about time it changed, > because it has grown outside of its boundries. Agreed. And I much prefer how you phrased your statement this time around, rather than the inflammatory initial version. "Horrid" is a pretty harsh way to describe someone's work. For my part, I'll try to thicken my own skin. Sorry for being a bit defensive. -- Dan Scott Laurentian University
