Fix failing rstcheck

[stevepiercy]

rstcheck is used by GitHub to validate README.rst files. See https://github.com/orgs/community/discussions/86715#discussioncomment-8431598. Currently the README.rst does not pass this validation, thus making the README no longer render.

This PR addresses all the validation issues, except for the XML code-blocks. For that, I need some guidance from the maintainers. Semantically XML is the correct language, but HTML passes rstcheck. Should I change the language from XML to HTML?

$ bin/rstcheck imp.rst
imp.rst:347: (ERROR/3) (xml) unbound prefix: line 1, column 0
imp.rst:409: (ERROR/3) (xml) unbound prefix: line 1, column 0
imp.rst:1025: (ERROR/3) (xml) unbound prefix: line 1, column 0
Error! Issues detected.

This PR also updates a few outdated links and some minor syntax improvements.

This PR solves:

1. Potentially address the GitHub rendering failure of README.rst.
2. Subsequently allow the Plone Documentation builds to pass CI https://github.com/plone/documentation/actions/runs/7861502462/job/21449928462#step:5:1195

[thet]

Regarding the XML issues, I'd instead just use:

.. code-block::

instead of:

.. code-block:: xml

these are only xml-snippets anyways. to make the rstchecker happy we would not only include the namespace definitions but also a proper xml root node i guess. and this would distract from the code block we wand to present here.

[stevepiercy]

@thet thanks, done in 4485874. OK to merge?

[thet]

@stevepiercy OK‌ to merge!