Hey Weilin and Calvin,
thanks for the feedback!
On 22.08.26 02:45, Calvin Buckley wrote:
On Aug 21, 2026, at 4:29 PM, Weilin Du <[email protected]> wrote:
In other words, if you and reviewers put the same effort into the content
itself,
would it be more effective to the topic "Moving php‑src/docs forward" than
rewriting it in different language?
See?
I say I don't object to the change because I don't think I have a say on
internal
doc, but I hope you can focus on the content itself instead of this if you want
to make the internal doc better. That is, update missing APIs through
UPGRAING.INTERNALS, building new chapters, writing articles for newcomers,
etc, etc.
That sounds way more better to me, and I am glad to see these contributions
happening
Cheers,
Weilin D.
Very much this. We have a ton of stale docs on i.e. the wiki, internals
book, etc. There was the effort to write more in docs/ (plus archiving
the old stuff in docs-old/). Changing the format is minor, rST I don't
think will pose a difficulty to people writing it more than Markdown in
the same place.
I totally get where you two come from, and I do not even disagree.
Adding new contents is my goal. But this step is a different task, and
it seems that I could not make entirely clear what it is about. Just in
case that's correct I'll try to make it clear now.
This task/effort started with this comment:
https://github.com/php/php-src/pull/13338#issuecomment-5263413385
Based on Ilijas answer these old docs must be checked and integrated
into the book, and that's what the PRs 23373 and 23374 do. So this whole
thing here is not "switch to Markdown because I like it so much", but
"get the old docs integrated". Those, however, are Markdown as many
other documents that must be integrated into the book. So the current
status is that we have Markdown /and/ reST documents. This means one of
either format must be converted to the other format, because we
logically do not want some pages to be rendered from Markdown and others
from reST. In fact, we have more Markdown lines than reST lines! And my
sole point is: since we must do one switch anyway, we should switch the
very few existing "demo state" book entries to Markdown instead the
other way around. For the multiple reasons I mentioned in the earlier
mails, and because as mentioned in the PR: "keep diffs when
moving/merging docs-old clean" -- ironically to avoid "churn". Because
the `docs-old` contents have content changes due to updates and removals
while integrating them; if those would be changed to reST in the same
time an understandable diff would be impossible.
To me that's just logical. That does make sense, doesn't it?
While typing all this I realise it was a bit unfortunate that I made the
Markdown PR the first in the stack; perhaps things would have been more
clear if the `docs-old` moves would have been in the first PR. But yeah,
I didn't expect that this will result in discussions in the first place,
so what I did was ordering the PRs in a way so that everything from
first to last PR remained fully renderable at all times.
---
Cheers
Nick
