Re: [PHP-DOC] Re: [PHP-DEV] "waldschrotts guide to nifty references" -manualpagedraft, version 0.9b From: Ron Chmara (ron <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 

--
Brought to you from iBop the iMac, a MacOS, Win95, Win98, LinuxPPC machine,
which is currently in MacOS land.  Your bopping may vary.