Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:67693
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 74.125.82.49 as permitted sender)
Message-ID: <51B83999.90103@gmail.com>
Date: Wed, 12 Jun 2013 10:04:25 +0100
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130510 Thunderbird/17.0.6
MIME-Version: 1.0
To: Nikita Popov <nikita.ppv@gmail.com>
CC: PHP internals <internals@lists.php.net>
References: <CAF+90c9PDHXOzd7p8-RJLuHGqrkcGS3JQJJ53zJKZga_ODi5gA@mail.gmail.com>
In-Reply-To: <CAF+90c9PDHXOzd7p8-RJLuHGqrkcGS3JQJJ53zJKZga_ODi5gA@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Subject: Re: [PHP-DEV] Internal object orientation documentation available!
From: ellison.terry@gmail.com (Terry Ellison)

On 10/06/13 19:33, Nikita Popov wrote:
> We just published some rather extensive documentation on internal object
> orientation:
>
>      http://www.phpinternalsbook.com/classes_objects.html
>
> This is part of a larger project aimed at documenting the engine and making
> it accessible to new contributors.
This looks like an excellent beginning so thanks.  A few general comments:

1)  I notice that your book is  "© Copyright 2013, Julien Pauli - 
Anthony Ferrara - Nikita Popov.  All Rights Reserved" rather than GDFL 
or one of the CC variants of open document licences.  They only issue 
that I see here is that I -- and possibly others -- might be a bit 
guarded in providing comment and input if that content was being 
transferred to the authors unconditionally.  Also if you are reserving 
all rights then you will need to be careful to ensure that all the 
content is yours and not extracted from an open or other 3rd party 
source.  Surely this going to add to your authoring burden?

2)  Wikipedia, for example, contains a lot of good in-depth explanation 
of CompSci concepts and standard patterns such as 
http://en.wikipedia.org/wiki/Hash_table. You might consider the content 
cut: when you include basic discussion of 101 principles (e.g. on 
HashTables); and when you limit
your content to their PHP-specific implementation, with suitable 
references to the 101 stuff. Tending to the former will make the book a 
lot longer, albeit standalone.  Your call, but I would have thought that 
the majority of the readership by nature will have some CompSci 
background and so want to skip the 101 stuff, or be referenced out to 
the appropriate in-depth WP or other reference.

3) What is your preferred markup format for feedback and contributions?  
E.g.  do you maintain an ODF or Docbook XML under some accessible git 
repository, or is is a case of (for example)

    hashtables/basic_structure.html para at line 138.  Not quite true that
    "the arBucket array will never shrink down: you can not reduce a PHP
    array, you only can grow it".  You can always implement your own
    resizer by realloing the arBucket array and the calling
    zend_hash_rehash() to do this. (This would be a good standard hash
    API function by the way.

But good luck and this will be an extremely useful project to help those 
wishing to get to grips with PHP internals.

Regards
Terry

(Resend including internals list)