Hi Nick
Thanks for bringing this up on the list.
Just to state my thoughts officially:
On 20.08.26 23:44, Nick Sdot wrote:
*Why Markdown:*
- not yet another syntax to deal with; we all write Markdown
reST is pretty popular, so not exactly something esoteric. Sure, I would
also guess that Markdown is more known, but reST is very hard to "learn"
either.
- renderable by default everywhere; including GitHub and IDEs
I don't think this holds.
Before:
https://github.com/php/php-src/blob/master/docs/source/core/data-structures/reference-counting.rst
After:
https://github.com/NickSdot/php__php-src/blob/6730bde4ee9ddfe618213441f83af70d49dc347f/docs/source/core/data-structures/reference-counting.rst
The problem here being that this isn't pure reST or Markdown, but MyST.
I'd guess the same goes for IDEs. Switching the names to .md might look
better for a good chunk of the file, but then the reST-like parts won't
render well anymore.
Please allow me this... If we actually want to move things forward, it
would be nice if we would not over-complicate and over-think
everything. Otherwise, things just stagnate and (almost) nothing
happens as we see with this started but never finished initiative.
I don't think "let's not overcomplicate" should be an argument for
"let's not question changes". Asking for good reasons for the switching
from one stack to another seems reasonable.
So to boil it down, these are internal docs, almost in the same "demo"
state as when they were introduced, not important C code. They were
introduced 2.5 years ago, yet they still have a big "work in progress"
banner, a bunch of todo's inline, and links to 404's (also meant as
todo's) in it. Plus, the overall activity to improve was rather
moderate. The only actual activity was in `release-process.md` --
which is already Markdown, and not touched by my PRs at all.
None of this is wrong, but I don't think the docs have stalled because
the syntax is too hard. Rather, more time should be designated to them.
It's just hard in today's climate, e.g. LLM security reports have taken
over a large chunk of our time, and even before that issues and user
docs seem more pressing.
The auto-formatter was also removed in your PR (there might not be one
for MyST?), I think that's worth mentioning.
Ilija
