Fix section numbering and levels

[mermshaus]

• Section 3.2 existed two times.
• Some headings were at the wrong level.

[Jean85]

This still looks wrong... I think the heading level is misaligned, with 4 (instead of 3) hashes

[mermshaus]

This still looks wrong... I think the heading level is misaligned, with 4 (instead of 3) hashes

Nice catch, you are right. Fixed.

Edit: Wait, it’s wrong in other places (in PSR-13), too. I knew I would regret this… 🐱 Give me a minute…

Edit 2: Okay, should be fine now. 👍

[mermshaus]

One might argue that ### References at the top is also on the wrong level (directly follows #), but I’d leave it as is because it seems to be this way for aesthetic reasons. 🤷

[KorvinSzanto]

Rather than bumping and breaking references / links in the wild I'd recommend moving the duplicate 3.2 item to the bottom

[mermshaus]

@KorvinSzanto:

Rather than bumping and breaking references / links in the wild I'd recommend moving the duplicate 3.2 item to the bottom

I think we can’t really change the order because the interfaces depend on each other.

With your idea, LinkProviderInterface would be the new 3.4, but 3.3 already is a subclass of that (EvolvableLinkProviderInterface extends LinkProviderInterface).

Edit: I agree that breaking links is not ideal, but I think that trying to be fully BC in cases like this is more trouble than it’s worth. With the HTML build pipeline that we have (e.g., no concept of revisions, afaik), I’m fine with pushing potential issues with breaking links to downstream.

[KorvinSzanto]

@mermshaus is there a practical reason they have to be in the order you're insisting on? I don't think the order really effects anything whereas changing the number of an entry no just breaks links but causes existing links to point to something different.

[mermshaus]

@mermshaus is there a practical reason they have to be in the order you're insisting on? I don't think the order really effects anything whereas changing the number of an entry no just breaks links but causes existing links to point to something different.

I’m pretty sure existing links won’t point to something different because the full heading is part of the hash. Because of this, you can actually link to the second 3.2 section right now.

But it’s true that the changes introduced in this MR will break the following links because their section number would change:

https://www.php-fig.org/psr/psr-13/#32-psrlinklinkproviderinterface
https://www.php-fig.org/psr/psr-13/#33-psrlinkevolvablelinkproviderinterface

Regarding practical reasons: If you read through the PSR, it would, like I said, feel odd to define a sub-interface before the interface it extends. It makes no sense in the context of reading order.

Let’s keep in mind that this MR, in my view, clearly fixes an obvious section-numbering oversight (bug). I think the consequences of two broken links to individual interface definitions are rather negligible. But I might be missing something.