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

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

To be fair, you created 8 PRs and pinged me only in the first one. So 
naturally that's what I look at and judge. But as I already said in my 
response, switching the file name to .md will fix some formatting issues 
while creating others. You'll need a custom MyST plugin to fix it. 
That's fine, but I'd like to remind you that your original argument was 
that reST is somehow not well supported by GitHub or IDEs, which is just 
incorrect.

I won't respond to the rest of your e-mail, as it reads like a rant and 
personal attack.

Ilija