Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:122568
X-Original-To: internals@lists.php.net
Delivered-To: internals@lists.php.net
Received: from php-smtp4.php.net (php-smtp4.php.net [45.112.84.5])
	by qa.php.net (Postfix) with ESMTPS id 1D7ED1AD8F6
	for <internals@lists.php.net>; Tue,  5 Mar 2024 14:53:58 +0000 (UTC)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=php.net; s=mail;
	t=1709650450; bh=9ZcKp+613oXD3lZ1CMHSyQn88bwny8s2Yx/d3xfWpl4=;
	h=References:In-Reply-To:From:Date:Subject:To:Cc:From;
	b=ZyLg+P1gjqXYLsfqQ9u3pnDXVV4PjbMtrEF9EW6I86UJpz2Y9MFFnFILIJZwWHjXw
	 WVtejeWAFEDnjLdmCRzMoF7GuRWI/9pgXTdpmti4empnih+OPUx5ZCyFm9k8pHhQP2
	 WWtGL/rZ77of4XdoPrZuhg/XUgum1tKeuyOrSjHHd+lESIDp4vC65F+f8y21LSnwsl
	 EhD0pI+oo56hrTbDz7cqjt8LNlGppc4sJupWzdEU/MrEAu/I6uygceTnHIdngdceuG
	 lHh+no0wDB8rEmFnkylyfbRxR8Wt2rZmk98fLLle2DbMRYvjn1XeWZCAjDy6n3COwe
	 3MOm8yHid6pjQ==
Received: from php-smtp4.php.net (localhost [127.0.0.1])
	by php-smtp4.php.net (Postfix) with ESMTP id 2CC9E18007F
	for <internals@lists.php.net>; Tue,  5 Mar 2024 14:54:09 +0000 (UTC)
X-Spam-Checker-Version: SpamAssassin 4.0.0 (2022-12-13) on php-smtp4.php.net
X-Spam-Level: 
X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED,
	DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,DMARC_PASS,FREEMAIL_FROM,
	RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,
	SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no
	version=4.0.0
X-Spam-Virus: No
X-Envelope-From: <landers.robert@gmail.com>
Received: from mail-ot1-f49.google.com (mail-ot1-f49.google.com [209.85.210.49])
	(using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
	 key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256)
	(No client certificate requested)
	by php-smtp4.php.net (Postfix) with ESMTPS
	for <internals@lists.php.net>; Tue,  5 Mar 2024 14:54:08 +0000 (UTC)
Received: by mail-ot1-f49.google.com with SMTP id 46e09a7af769-6e4e51b0bfcso835057a34.0
        for <internals@lists.php.net>; Tue, 05 Mar 2024 06:53:56 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=gmail.com; s=20230601; t=1709650436; x=1710255236; darn=lists.php.net;
        h=content-transfer-encoding:cc:to:subject:message-id:date:from
         :in-reply-to:references:mime-version:from:to:cc:subject:date
         :message-id:reply-to;
        bh=9ZcKp+613oXD3lZ1CMHSyQn88bwny8s2Yx/d3xfWpl4=;
        b=ATxfRWnAtgPT3pItKBhDSQ6dlpmXYOKbdzAI+/FFZAG3ElF7sCr87rW7RY9SGvkXDp
         hrNthMBGA8j+3QFJfILSulsmIa5aA1ycCi95EVdMIU43DKdjMYht2hbPf5CE1spuFTSW
         cft4/qpdmitviF22xZZGW3DEq5U46mrisLE2gCmYiPGE0c3eqeGBYlcSbNuIH6TLrzlN
         U8eo7eu7Cto9kOP0Zo2R3EzY/PddaCcZCbcMIwx/DCosYY52ZWIwzIpB7+xu0FgdhbYw
         QIL4RlCrvNWfAPm0JEeoLZJop1YyTIHhgsY0TqhGI6lBtGe5U79ZDJjXoeCqbR8s7h8e
         vzFg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
        d=1e100.net; s=20230601; t=1709650436; x=1710255236;
        h=content-transfer-encoding:cc:to:subject:message-id:date:from
         :in-reply-to:references:mime-version:x-gm-message-state:from:to:cc
         :subject:date:message-id:reply-to;
        bh=9ZcKp+613oXD3lZ1CMHSyQn88bwny8s2Yx/d3xfWpl4=;
        b=SBE/rJ9RnGukxFHnnrDJ0TJYuh6eVdobonDRGgqtMWWe39iwiKy5JwniOEnNH6wW3n
         asygdvZg1hHkXKBxjUxgD0P5TeNjtY/OfFwd2ZY4FMqnKEh0/ebHkibcblPAPzG5VpRV
         JKUi2xzb5Oo//3JN3MdL6SXlmZzA+6ir0+aSg0Ar36SxAXpv5k/m2zotEVldd1tQBiDQ
         KPVv28qweFRR8VDWIyJo2vgfX39HW0nh4AM1c/wmQ/5xzOQRTrkKyvsaLpqWmL5CODVp
         8UlpG3Taja54iBjoABayBoEzg6yjoniZ3kEWJ9JeVYXvB6grAI+hyyQiFYKsikPbHJ/+
         K5KQ==
X-Forwarded-Encrypted: i=1; AJvYcCWtyiTYkw2zuKCyGM1bykiSz7PbKPJMuGC3Uc+YOCDbVtUTaCYxqkOTinAgFfCPwXuT79oacuyaoQ2tRGHsRhyozNkowYRfMA==
X-Gm-Message-State: AOJu0YwS9vWolVX5++BX11kAv/Sgx9wgMfA/6H0xRacYdWKTfQQ9vCiM
	nlPgAqkoaDw8ZJCvKepY0Zk+SKXHb2K+K64n8PP5v6BTIhoBTS99z1HKV9k8o0f4O9e30/Sp1YL
	JG6bYTMQ6wg3+YnldllXqWTfYqRI=
X-Google-Smtp-Source: AGHT+IFY3bWsXOfEC1iKDThPHcNWP2HCOe8YACftI08uh+ahIt99MSheHfKccP36cnb3Wos/nMOR9jmo4idPp5aSjeM=
X-Received: by 2002:a9d:6654:0:b0:6e2:e00d:8e41 with SMTP id
 q20-20020a9d6654000000b006e2e00d8e41mr2025928otm.17.1709650435677; Tue, 05
 Mar 2024 06:53:55 -0800 (PST)
Precedence: bulk
list-help: <mailto:internals+help@lists.php.net
list-unsubscribe: <mailto:internals+unsubscribe@lists.php.net>
list-post: <mailto:internals@lists.php.net>
List-Id: internals.lists.php.net
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