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

Hey Jordi,

thanks for the feedback!

On 21.08.26 06:01, Jordi Kroon wrote:
> Besides the docs folder, RST is also currently used for UPGRADING, 
> UPGRADING.INTERNALS and NEWS. Changing these files to another format 
> will break things as they depend on that specific format (e.g 
> https://github.com/php/web-php/blob/master/bin/news2html internally, 
> but external sites parse these files as well).

This is a non-argument because these documents are not and will not be 
part of the book. Different context, different consumers. They will not 
be touched, and are not relevant here. Bringing those up here is like 
saying we cannot migrate the internals book to Markdown because `doc-en` 
is XML.

> So given that it does make sense that the docs are also written in the 
> same format for consistency. Not ignoring the fact that there are MD 
> files as well. 

Also doesn't make sense because you ignore that we unavoidably will have 
"churn" in one or the other direction to integrate `docs-old` that are 
already Markdown. Although I'd really love to be one, I am unfortunately 
not a magician -- hence, I cannot make the impossible 'smallest diff 
with no "churn' at all' possible because we have source documents in 
both formats.

Making it Markdown is more sensible; you even say you prefer it yourself.

---

Cheers
Nick