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. -- Dan Scott Laurentian University
