Re: [PHP-DEV] Moving `php-src/docs` forward

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