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
