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. 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
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
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.
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.
- Tul
