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

Hey Ilija,

thank you too for the feedback!

On 21.08.26 05:26, Ilija Tovilo wrote:
> 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. 


That's only because you picked a commit from a non-final state that 
solely exists to keep diffs small; mind the still existing `.rst` 
extension. I would really appreciate if you could please at least once 
look at the final PR instead of bit by bit arguing about non-final state.

Here is the real picture...

Before:
https://github.com/php/php-src/blob/master/docs/source/index.rst
After:
https://github.com/NickSdot/php__php-src/blob/docs/restructure-08/docs/source/index.md

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/docs/restructure-08/docs/source/core/memory-management/reference-counting.md

The only thing that cannot render perfectly are the non-standard tables 
you asked for. Yet their contents are still very readable (in fact the 
raw format you prefer in code) and still stand out (same as TOC; same in 
reST/Markdown), reST renders eg important warnings/notes as plain text, 
which is stupid That the Markdown syntax is much less noisy is proven by 
the diff. Also, let me quote yourself from an internals message:

 > That said, reStructuredText is far from perfect itself.

So if you now gonna argue that:

- rendering tables is more important than rendering important (!) 
warnings/notes that by definition should be highlighted
- using the syntax all of use daily is not better in general
- suddenly reST which you called "far from perfect" has to be defended 
at all cost

I will gonna fall off my chair for real.

Could you please address:

- why the demo state of the docs would justify being so picky
- why this is a blocker at all if we will have unavoidable "churn" one 
or the other way because of `docs-old`
- my point that much of this anyway will be touched/replaced in the 
process of getting things updated

You are literally making any progress impossible by requiring no "churn".

>> 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.

As mentioned above, I'd really appreciate if you would get the full 
picture, as in look at least once at the final PR, before questioning 
bit by bit based on non-final state picks. I'd also appreciate if you 
would not leave the good reasons I added unaddressed/ignored.
>> 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.

As I mentioned, understandable that y'all are busy with other things. 
That's why I am offering to help out. :)

> The auto-formatter was also removed in your PR (there might not be one 
> for MyST?), I think that's worth mentioning.


Nah, that's not really dropped. It's re-activated in a later branch. 
Reason for deactivating temporarily was your smaller diff requirement 
for the first PR. I didn't open the last branch PR yet because it is WIP 
to handle feedback 
(https://github.com/php/php-src/commit/0d4035b98bfd5e5d97c5b515cf6630d685b34545) 
without requiring me to rewrite all commits in all branches each time. 
And, it is literally mentioned in the very diff you saw the removal in.

> Ilija 

---

Cheers
Nick