Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:67698
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.219.54 as permitted sender)
MIME-Version: 1.0
In-Reply-To: <51B83999.90103@gmail.com>
References: <CAF+90c9PDHXOzd7p8-RJLuHGqrkcGS3JQJJ53zJKZga_ODi5gA@mail.gmail.com>
	<51B83999.90103@gmail.com>
Date: Wed, 12 Jun 2013 22:04:42 +0200
Message-ID: <CAF+90c9z+4E9iez2hjQ0XFKYgUQHf1HhMg1zTZe_ddPsTuePVg@mail.gmail.com>
To: Terry Ellison <ellison.terry@gmail.com>
Cc: PHP internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=089e0111b88648bf2f04defa8655
Subject: Re: [PHP-DEV] Internal object orientation documentation available!
From: nikita.ppv@gmail.com (Nikita Popov)

--089e0111b88648bf2f04defa8655
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Wed, Jun 12, 2013 at 11:04 AM, Terry Ellison <ellison.terry@gmail.com>wr=
ote:

> 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<http://www.p=
hpinternalsbook.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  "=A9 Copyright 2013, Julien Pauli - Antho=
ny
> 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 he=
re
> 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?
>

This is just a legal precaution, because we are not yet exactly sure about
the publishing formats for this project. If we wanted to actually have a
(printed) book, then questions of ownership can become problematic. Anyway,
I'm pretty sure that we will publish this under a CC license eventually.

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<http://en.wikipedia.org/wiki/Ha=
sh_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 l=
ot
> longer, albeit standalone.  Your call, but I would have thought that the
> majority of the readership by nature will have some CompSci background an=
d
> so want to skip the 101 stuff, or be referenced out to the appropriate
> in-depth WP or other reference.
>

We don't have particularly much "101 stuff" to cover (basically just
hashtables), in which case I think its better to include a small
introduction to the topic to make things self-contained. Also, this project
is targeted not just at developers with years of C experience, but also at
people coming from a more higher-level (PHP) background, in which case
intimate knowledge of things like hashtables probably can't be expected.


> 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.


Heh, how did you get to that page? Wasn't supposed to be linked anywhere,
as that chapter isn't done yet. In any case, we are writing this in RST
(reStructured Text) in a private git repo (which will be made public
sometime down the road). So if you have feedback, no need to write text in
any particular format, just point us to what wrong / missing (or any other
suggestions) and we'll fix it.

Regarding your particular example: Agree that this wasn't right in that
formulation. The text now says "while the arBuckets array automatically
grows, it will *not* shrink when you remove elements". I would rather not
mention the hack to implement the shrinking though, because its bad style
to directly mess with the members of the HT.

Thanks for your feedback Terry!

Nikita

--089e0111b88648bf2f04defa8655--