Newsgroups: php.internals Path: news.php.net Xref: news.php.net php.internals:122567 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 7AFAA1AD8F6 for ; Tue, 5 Mar 2024 13:45:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=php.net; s=mail; t=1709646362; bh=9LJJ/D2e8aWJnQB38qdqWYNORUCx6YjeuB6D2Ussaf0=; h=References:In-Reply-To:From:Date:Subject:To:Cc:From; b=OCYTXRxnXPLQwceYyOpcfulJ7tWNiq79BE0R2oK2UrfHoUvuaWuyXDW5+jAfUm08h bd7FXyAk0lGl0KnH+69fRdTNmltFAh/L8vIJrVo52Mw/jmqImo1eKTrPcNGhe8qleW IexEUamBZSn+taO4FvkJjOF+LTb3ISc20MpI9JeT3lZTOATBgetESc1vrUkY0KXfvr EXpwYSLBWJzF6vA0orld/VbXt4ie+tISDQB2IzEXZrjBC3+dWlZlf+MOrjp2tUC0yY aYPjLYW343l42sPZ2NZWtGPKC1E+mCONzT0ZwiwJT6W8HLZW/lgetqbF3WG9OnfPgR ZucB373UJZFUA== Received: from php-smtp4.php.net (localhost [127.0.0.1]) by php-smtp4.php.net (Postfix) with ESMTP id 7BE4D1801D9 for ; Tue, 5 Mar 2024 13:46:01 +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=0.2 required=5.0 tests=BAYES_20,DMARC_MISSING, FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM,HEADER_FROM_DIFFERENT_DOMAINS, HTML_MESSAGE,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,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: Received: from mail-ej1-f48.google.com (mail-ej1-f48.google.com [209.85.218.48]) (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 ; Tue, 5 Mar 2024 13:46:00 +0000 (UTC) Received: by mail-ej1-f48.google.com with SMTP id a640c23a62f3a-a3fb8b0b7acso723568966b.2 for ; Tue, 05 Mar 2024 05:45:48 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709646347; x=1710251147; h=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=9LJJ/D2e8aWJnQB38qdqWYNORUCx6YjeuB6D2Ussaf0=; b=cHBPhWlVg1R1NXg1awgnYpcbNgrpMy+oLKve7oqtZ6knPhTrVRcZBAa3Es2k15kTkl m20aH5qgy16P+V4Qho4rsZL5vV9bJaxuu0E3u4jo4l/URHSIhL6xV0N8qy/sFm395B7Z 9GbKCtCY1YRAmTHG1H4bf6Ud8KF+YtPPrlqP/TvncFzmT4amEWcKp7lTJuKjFVmrmLBe 8tN9o5uRpPkXib2P1mTEQINjp51OLvtc8JkvI9VXrUsd5nTZmQkuWwu3FCJMQiVwX+iE 7gfgbmgDaY3ZPJAjvHhjYn6VyoJv6EUzdNAsseTzacQI53K8etwsDIVEDCsNV/xJdmZC Vokg== X-Forwarded-Encrypted: i=1; AJvYcCUxvxuRmDcneZ42obcmhecIhFauj2yNMFCKpnQTQg7ADcdE1Z+Y+dTfExUd94qaxcdBsZiFIl3XwkRLwoFzRMQux8DITR8rdg== X-Gm-Message-State: AOJu0YzoI7zcJe6eQy1hp/of83QcYb7WXBUnwBQU4OpKAQO8h1CMlYdC 18X/hf4uZvCr2nBWoSfuiQ1uKTnBP2GRfyoHXs9W+NQrsIvgBvWhp7EEsOyxibQnCcqhlXzQKHl DzY8Vplo+mm+bmix3tqfXtfakeROHGVT09JM= X-Google-Smtp-Source: AGHT+IF5kasd49kS8rO72LdQW2iwKevOyJDr8Gkdu7BvL+/mN7XgTihH8XTkK34xRygGqbzs0M8ZVFpbUqcsF4W+YpQ= X-Received: by 2002:a17:906:c7cc:b0:a44:7a34:e620 with SMTP id dc12-20020a170906c7cc00b00a447a34e620mr8349207ejb.4.1709646347148; Tue, 05 Mar 2024 05:45:47 -0800 (PST) Precedence: bulk list-help: list-post: List-Id: internals.lists.php.net MIME-Version: 1.0 References: In-Reply-To: Date: Tue, 5 Mar 2024 13:45:36 +0000 Message-ID: Subject: Re: [PHP-DEV] php-src docs To: Peter Kokot Cc: Ilija Tovilo , PHP internals Content-Type: multipart/alternative; boundary="00000000000036a6040612ea0fb9" From: bukka@php.net (Jakub Zelenka) --00000000000036a6040612ea0fb9 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Hi, On Tue, 5 Mar 2024 at 12:48, Peter Kokot wrote: > On Mon, 12 Feb 2024 at 12:13, Ilija Tovilo 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 > wrote: > > > > > > 2024=E5=B9=B42=E6=9C=8811=E6=97=A5(=E6=97=A5) 21:18 Ilija Tovilo : > > > > > > > > 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 > problem. > > > > 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? The problem with this is that it gets easily outdated. If it=E2=80=99s in t= he same repo, we can ask for updates during PR and have it as part of review. Because > once this will increase in number of files, also php-...tar.gz archive > files will increase and everything will become more complex. Are you talking about release tarball that RM creates or git archive (github) one? If the former, then we can filter the docs out and if latter, than I=E2=80=99m not sure why we should care? It will > also mess the php-src Git log with documentation changes. The way how I see it is that internal docs are part of code or its addition so I wouldn=E2=80=99t think it can mess up our git logs that are largely ir= relevant anyway. 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 Isn=E2=80=99t this dead and hugely outdated? Cheers Jakub --00000000000036a6040612ea0fb9 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
Hi,

On Tue, 5 Mar 2024 at 12:48, 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@gmail.com> wrote:
> >
> > 2024=E5=B9=B42=E6=9C=8811=E6=97=A5(=E6=97=A5) 21:18 Ilija Tovilo = <tovilo.ilij= a@gmail.com>:
> > >
> > > Hi everyone.
> > >
> > > I would like to start an initiative to centralize documentat= ion of the
> > > PHP internals.
> > > https://github.com/php/php-src/pull/13338
> > > https://iluuu1994.github.io/php-src/ (will be= moved to php.github.io
> > > once merged)
> > >
> > > Let me know of any thoughts and suggestions you might have.<= br> > >
> > Hi, Ilija.
> > Thank you for your great suggestion.
> >
> > It seems make sense to have a set of documents about the structur= e of
> > php-src in php-src.
> > Easily create pull requests to them.
> >
> > Although I have to learn reStructuredText, It is not seems major = problem.
>
> 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?
The problem with this is that it= gets easily outdated. If it=E2=80=99s in the same repo, we can ask for upd= ates during PR and have it as part of review.

Because
once this will increase in number of files, also php-...tar.gz archive
files will increase and everything will become more complex.

Are you talking about release t= arball that RM creates or git archive (github) one? If the former, then we = can filter the docs out and if latter, than I=E2=80=99m not sure why we sho= uld care?

It will
also mess the php-src Git log with documentation changes.

The way how I see it is that inte= rnal docs are part of code or its addition so I wouldn=E2=80=99t think it c= an mess up our git logs that are largely irrelevant anyway.

And the doc= s
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-lan= gspec

Isn=E2= =80=99t this dead and hugely outdated?

Cheers

Ja= kub
--00000000000036a6040612ea0fb9--