Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:122568
Precedence: bulk
MIME-Version: 1.0
References: <CAPyj-LCnOYmMv4b0bxGaHsS-0j8ptjTt95f48Zt_JUQh6NB_8g@mail.gmail.com>
 <CAEPPVa0rUkgajvApdiA+KVQMKALnG2cFTCPisanKSx1hbc6h=A@mail.gmail.com>
 <CAPyj-LAeaiv64_7Y_RUsRf9wHOdbfAYqtUvr-Qu36OrN_OKjxQ@mail.gmail.com> <CAAfnsFX0Nb8u9OMHQUyVyD_ZA31_E1_CCQgGyPzp7uGZr6qBog@mail.gmail.com>
In-Reply-To: <CAAfnsFX0Nb8u9OMHQUyVyD_ZA31_E1_CCQgGyPzp7uGZr6qBog@mail.gmail.com>
Date: Tue, 5 Mar 2024 15:53:44 +0100
Message-ID: <CAPzBOBOY17sTejdEwmt-2iG+1ZpfW53qLa23cFuHvvsXeNfP5A@mail.gmail.com>
Subject: Re: [PHP-DEV] php-src docs
To: Peter Kokot <petk@php.net>
Cc: Ilija Tovilo <tovilo.ilija@gmail.com>, PHP internals <internals@lists.php.net>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
From: landers.robert@gmail.com (Robert Landers)

On Tue, Mar 5, 2024 at 1:48=E2=80=AFPM Peter Kokot <petk@php.net> wrote:
>
> On Mon, 12 Feb 2024 at 12:13, Ilija Tovilo <tovilo.ilija@gmail.com> wrote=
:
> >
> > Hi Yuya
> >
> > It seems you accidentally sent your response to me instead of the list.
> >
> > On Sun, Feb 11, 2024 at 5:10=E2=80=AFPM youkidearitai <youkidearitai@gm=
ail.com> wrote:
> > >
> > > 2024=E5=B9=B42=E6=9C=8811=E6=97=A5(=E6=97=A5) 21:18 Ilija Tovilo <tov=
ilo.ilija@gmail.com>:
> > > >
> > > > Hi everyone.
> > > >
> > > > I would like to start an initiative to centralize documentation of =
the
> > > > PHP internals.
> > > > https://github.com/php/php-src/pull/13338
> > > > https://iluuu1994.github.io/php-src/ (will be moved to php.github.i=
o
> > > > once merged)
> > > >
> > > > Let me know of any thoughts and suggestions you might have.
> > >
> > > Hi, Ilija.
> > > Thank you for your great suggestion.
> > >
> > > It seems make sense to have a set of documents about the structure of
> > > php-src in php-src.
> > > Easily create pull requests to them.
> > >
> > > Although I have to learn reStructuredText, It is not seems major prob=
lem.
> >
> > For some context, I initially planned to go with the mdBook from the
> > Rust project (https://github.com/rust-lang/mdBook/) as Markdown is a
> > bit more approachable. After writing the sample zval chapter, I
> > noticed some pain points in terms of formatting, most significantly
> > tables. That said, reStructuredText is far from perfect itself.
> >
> > As mentioned previously, the other reason for choosing Sphinx was that
> > it is quite extensible.
> >
> > Ilija
>
> Wouldn't it be simpler and better in the long run to have a separate
> Git repository for the PHP language internal documentation? Because
> once this will increase in number of files, also php-...tar.gz archive
> files will increase and everything will become more complex. It will
> also mess the php-src Git log with documentation changes. And the docs
> subdirectory in the php-src can be still used for some possible other
> files that are needed for the GitHub interface usage. Now we have the
> docs-old subdirectory in php-src, which is a bit messy and it might
> take a while to migrate all those to RST. It would be also perhaps
> smart to sync this initiative with https://github.com/php/php-langspec
> somehow or at least to display all of those together in some GH page.

Personally, the documentation is part of the code it documents,
otherwise, you don't have documentation, you have content that can be
mistaken for documentation.

Robert Landers
Software Engineer
Utrecht NL