[PHP-DOC] Manual structure (was: [PHP-DOC] Re: "waldschrotts guide to nifty references") From: Lars Torben Wilson (torben <email protected>)
Date: 08/20/00

[New thread 'cause this is getting longish. :)]

OK, so everybody seems to think *something* needs to be done; we're
just trying to agree on what. Here are some of my ideas

Stanislav Malyshev writes:
> RC>> Actually, you're not exaggerating, at all, about what the users have been
> RC>> looking for, and are *already using* the PHP manual for.
> RC>>
> RC>> http://www.php.net/manual/function.imagecreate.php
> RC>>
> RC>> Has a sample chunk of code to build.... a clock.
>
> No, it's annotations that have.

I think that was the point.:) But it's very true, you weren't really
exaggerating by much. The errata are full of examples, code snippets
(and whole programs), tutorials, hints, questions, and so forth and so
on ad nauseum. People are looking for information--and the manual
seems to be the natural place to look.

Now, when I first started working with the new manual structure (back
in pre-PHP 3 days), I was surprised to find that the
non-function-reference section was so small. It seemed at the time
that the function reference should be something that was referred to
by the manual, like an appendix. I guess I was drawn toward viewing
the manual as a large book: 'This is PHP and this is how it
works'. *Not* just as a function/operator reference.

One idea would be to have short examples in the function references,
but when spare time becomes available (and we're all shovelling snow
for the Dark Prince), it would be good to get some attention paid to
the Getting Started and Features sections. Maybe rename them. It seems
like a natural place to introduce the usage of the language, and some
common applications (in the 'applied PHP' sense, not the 'word
processor' sense) to which it can be put. Including examples and
common pitfalls. Then, the references remains as a more man-page-ish
reference to the actual usage of the functions and language. I think
that something like this would A) keep the function reference concise,
clear, and useful, and B) provide a good place to look for help
learning about PHP and how to use it effectively.

One other effect which an approach (somewhat) like this would have:
the amount of information would increase, and the function reference
size/bloat would *not*. And what the hell--we already have Quick Ref
(which I use almost hourly) and a fully functional search engine. We
have a great XML structure, which enables us to do something like this
without bloating other parts of the manual, and for those who don't
want to bother with the rest of it, it's already possible simply to
bookmark the Function Reference TOC page and skip the rest.

> And annotated manual is not tutorials. That's like calling Slashdot an
> university :)

This is very true. Many of the 'tutorials' in the errata are just
plain wrong, or at least strangely misguided.

> RC>> PHP Manual = Users Guide PHP Reference = Stripped of all code
> RC>> examples, tutorials, descriptions, etc. Just raw syntax from the
> RC>> main tree. This could be done programatically, as in (from
> RC>> array.xml):
>
> Good. Now if you also divide it in different files, for the sake of
> modularity, my dream is perfect :) Though, maybe just a good XML editor
> might help...
>
> --
> Stanislav Malyshev stas <email protected>
> +972-3-6139665 ext.106

Following is a rough idea of what I'm thinking about, although
obviously it needs a *lot* more thought. I'm not just talking about
subclassing the Function Reference here; I'm talking about using it as
what it was meant to be: a reference of functions.

Typically, those who need a function reference, know that's what they
need. They wouldn't be bothered with the extraneous cruft of
tutorial-style writing, because that'd be in the 'Using PHP'
section. Those who need that 'cruft' would be able to easily find
it. And better introduction to the general concepts of PHP may be
useful to many. For instance, a pretty hefty percentage of function
errata are actually based on misunderstandings of how strings,
references, and scoping work.

I'm just throwing this out there as an idea. I don't really expect
this to appeal to everyone, but at least it can serve as a target to
shoot up while hashing out something that works for everyone--or at
least a concensus majority :). So fire away.

Table of Contents
Preface
     About this Manual
I. Getting Started
     1. Introduction
     2. Features
     3. Installation
     4. Configuration
     5. Security
II. Using PHP
     14. Error handling
     15. Creating and manipulating images
     16. HTTP authentication with PHP
     17. Cookies
     18. Handling file uploads
     19. Using remote files
     20. Connection handling
     21. Persistent database connections
...etc...
III. Language Reference
     5. Basic syntax
     6. Types
     7. Variables
     8. Constants
     9. Expressions
     10. Operators
     11. Control Structures
     12. Functions
     13. Classes and Objects
IV. Function Reference
     21. Basic functions -\
     22. Database functions > Or whatever...
     23. Extensions -/
...etc...
V. Appendixes
     A. Migrating from PHP/FI 2.0 to PHP 3.0
     B. Migrating from PHP 3.0 to PHP 4.0
     C. The PHP Debugger
     E. PHP internals 

-- 
+----------------------------------------------------------------+
|Torben Wilson <torben <email protected>>                     Netmill iTech|
|http://www.coastnet.com/~torben            http://www.netmill.fi|
|Ph: 1 250 383-9735                             torben <email protected>|
+----------------------------------------------------------------+