Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:67703
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 209.85.128.180 as permitted sender)
MIME-Version: 1.0
Sender: julienpauli@gmail.com
In-Reply-To: <CAF+90c9z+4E9iez2hjQ0XFKYgUQHf1HhMg1zTZe_ddPsTuePVg@mail.gmail.com>
References: <CAF+90c9PDHXOzd7p8-RJLuHGqrkcGS3JQJJ53zJKZga_ODi5gA@mail.gmail.com>
 <51B83999.90103@gmail.com> <CAF+90c9z+4E9iez2hjQ0XFKYgUQHf1HhMg1zTZe_ddPsTuePVg@mail.gmail.com>
Date: Thu, 13 Jun 2013 18:54:49 +0200
Message-ID: <CAMUwpuQuYKvtjsLN2euT8Skb4HXnqXWPiYmCfLSd_Wd4hDnFTw@mail.gmail.com>
To: Nikita Popov <nikita.ppv@gmail.com>
Cc: Terry Ellison <ellison.terry@gmail.com>, PHP internals <internals@lists.php.net>
Content-Type: multipart/alternative; boundary=089e01294a806be23c04df0bff66
Subject: Re: [PHP-DEV] Internal object orientation documentation available!
From: jpauli@php.net (Julien Pauli)

--089e01294a806be23c04df0bff66
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

On Wed, Jun 12, 2013 at 10:04 PM, Nikita Popov <nikita.ppv@gmail.com> wrote=
:

> On Wed, Jun 12, 2013 at 11:04 AM, Terry Ellison <ellison.terry@gmail.com
> >wrote:
>
> > On 10/06/13 19:33, Nikita Popov wrote:
> >
> >> We just published some rather extensive documentation on internal obje=
ct
> >> orientation:
> >>
> >>      http://www.phpinternalsbook.**com/classes_objects.html<
> 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  "=A9 Copyright 2013, Julien Pauli - Ant=
hony
> > Ferrara - Nikita Popov.  All Rights Reserved" rather than GDFL or one o=
f
> > 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 ne=
ed
> > 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 yo=
ur
> > authoring burden?
> >
>
> This is just a legal precaution, because we are not yet exactly sure abou=
t
> the publishing formats for this project. If we wanted to actually have a
> (printed) book, then questions of ownership can become problematic. Anywa=
y,
> 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 o=
f
> > CompSci concepts and standard patterns such as
> > http://en.wikipedia.org/wiki/**Hash_table<
> http://en.wikipedia.org/wiki/Hash_table>.
> > You might consider the content cut: when you include basic discussion o=
f
> > 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 th=
e
> > 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.
> >
>
> 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 proje=
ct
> is targeted not just at developers with years of C experience, but also a=
t
> 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 th=
at
> >    "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 i=
n
> any particular format, just point us to what wrong / missing (or any othe=
r
> 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.
>
> Yes that was my writings. As I'm not English :-) I may miss words or
sometimes turn sentences to a different meaning from what I initially
thought in my native language.

Nikita fixes that ;-)

Julien.Pauli

--089e01294a806be23c04df0bff66--