Re: [PHP-DOC] Re: [PHP-DEV] "waldschrotts guide to nifty references"-manualpagedraft, version 0.9b From: Sterling Hughes (sterling <email protected>)
Date: 08/20/00

> Stanislav Malyshev wrote:
> > HH(>> if we have different <book>s or one big <book> with
> > HH(>> different <part>s as long as as much core information is
> > HH(>> available in a structured way in _one_ place as possible
> > For me, it does. I believe the way of thinking means a lot (call me
> > strange). If you think PHP Users Guide and PHP Manual is one book, you
are
> > tempted to put entire chapter on how to write web counter somewhere into
> > "imagegif" chapter. I know I'm exaggerating, but the point is that
logical
> > division is important, not the gory details.
>
> Actually, you're not exaggerating, at all, about what the users have been
> looking for, and are *already using* the PHP manual for.
>
> http://www.php.net/manual/function.imagecreate.php
>
> Has a sample chunk of code to build.... a clock.
>
> This is the level of detail they are looking for in the documentation.
>
> What is the cost of putting it in there? We've discussed compile time,
> there's also megabytes for storage (in the db or in the), and difficulty
> of UI (information structuring).
>
> Perhaps if we looked at this from another perspective: What we are
> talking about may _not_ be about adding more documentation, but
> splitting out a tree of _less_ documentation. In O'reilly terms,
> we are talking about a "nutshell" book vs. a full reference, so perhaps
> considering leaving the "full" version as is, and making a "concise"
> version from it.
>
> IOW:
> PHP Manual = Users Guide
> PHP Reference = Stripped of all code examples, tutorials, descriptions,
> etc. Just raw syntax from the main tree. This could be done
programatically,
> as in (from array.xml):
>
> <refentry id="function.array">
> <refnamediv>
> <refname>array</refname>
> <refpurpose>
> Create an array
> </refpurpose>
> </refnamediv>
> <refsect1>
> <title>Description</title>
> <funcsynopsis>
> <funcprototype>
> <funcdef>array <function>array</function></funcdef>
> <paramdef>mixed
> <parameter><optional>...</optional></parameter>
> </paramdef>
> </funcprototype>
> </funcsynopsis>
> /*(delete from here, from close funcsynopis to the refsect) */
> </refsect1>
> </refentry>
>
> Small, tight, fast, no tutorial code "examples" or other added ancillary
> information.
>
> -Bop

We currently have such a tool:

./genfuncsummary > /php4 > function_summaries

Function summaries will contain a list of all the proto's in the PHP source
+ a small description:

int virtual(string filename)
    Perform an Apache sub-request

-Sterling