Bug#932957: #932957 Please migrate Release Notes to reStructuredText

[Holger Wansing <hwansing@mailbox.org>]

[[ debian-devel in CC, to get a wider audience regarding reStructuredText ]]


Hi,

I worked on this recently, and I have something like a prototype ready.
It can be found (as html) at
https://people.debian.org/~holgerw/release-notes_sphinx/
while the git repo containing the migration is at
https://salsa.debian.org/holgerw/release-notes


However, I may have some objections against the migration at all:
as far as I know, sphinx/reStructuredText is still lacking some functionality,
which is heavily used in the release-notes.
That is the use of substitutions within URLs.
In docbook speach these were entities, and you could use them in URLs like this:

    Please follow the instructions in the <ulink
    url="https://www.debian.org/releases/&oldreleasename;/releasenotes";>Release
    Notes for &debian; &oldrelease;</ulink> to upgrade to &debian;
    &oldrelease; first if needed.

Please note the &oldreleasename; in the URL!
I could not get this working with sphinx (if someone knows better, please
contact me!)
In sphinx, I used hardcoded codenames like
https://www.debian.org/releases/bullseye/releasenotes instead, which means,
that there is much work to do to make the release-notes fit for the next release,
while with docbook you only need to change the entity in one place !!!
In sphinx you need to change every single occurence, and don't forget the 
translations !!!



Beside this, I need help to adapt the buildchain, to get the possibility of
building the release-notes for the different architectures.
I have no python knowledge, so I will most likely not get this running myself.

And the last point is the integration into the debhelper tools: I don't know
if it is required, to have the release-notes fit for building as a whole
package with sbuild or debuild or similar. Salsa tries to build it via CI
at every push, but currently fails.
However, there is no package "release-notes" in the archive, so currently
it is only a matter of building it on wolkenstein for www.debian.org, right?


Regards
Holger



-- 
Holger Wansing <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076