On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwansing@mailbox.org> wrote:
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/
I hope the below doesn't come across as negative - it;s not meant to
be: i've been submitted MRs for release-notes and
found the XML syntax adds complexity to the source that mostly only
results in the output using bold or fixed-width:
So it would be great to simplify to rst!
Unfortunately, my first impression is that it the output has quite a
few issues which make it a lot harder to read than
the docbook version - which im sure is because it's still only a
prototype, but thought it might helpful to list the things that jumped
out at me:
- It is a lot more cluttered than the docbook version - it feels
off-putting and dense to read
- it's all a bit 'blue' - i'd suggest red is more on-brand for debian
- the "next"/"prev" links at the bottom-right are white on green ---
I totally missed at first, and found hard to read
- i was a bit confused by the "12.1" version number at the bottom of
every page, and having 'sphinx' reminded me of websites with "hosted
by geocities"
- are the red hyphens in eg the 'deb...' line near the top of
https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html
meant to be red? (maybe it is a syntax error?)
- package names are no longer distinguished from other text (eg 'ntp'
in https://people.debian.org/~holgerw/release-notes_sphinx/en/html/issues.html#changes-to-packages-that-set-the-system-clock)
- the order in the contents pane on the left is a bit...unusual: it
starts with the current section, then does previous, then next, so eg
on chapter 2,
https://people.debian.org/~holgerw/release-notes_sphinx/en/html/whats-new.html
it lists chapters 2, then 1, then 3.
- https://people.debian.org/~holgerw/release-notes_sphinx/en/html/genindex.html
is completely blank
- not sure "show source" on the left is all that useful for readers
I'm sure these are easy to fix!
while the git repo containing the migration is at
https://salsa.debian.org/holgerw/release-notes
Im sure i am being dumb, but i couldnt spot where the actual rst files
are? - i still see eg
https://salsa.debian.org/holgerw/release-notes/-/blob/master/en/issues.dbk
in XML
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.
You could always keep the entities and do a 'sed
s/&oldrelease;/bookworm/g' etc before "building" with sphinx.
Actually.... if i click 'show source' l get to
https://people.debian.org/~holgerw/release-notes_sphinx/en/html/_sources/about.rst.txt
which seems to have |RELEASE| and |RELEASENAME| rather than 12 and
bookworm: perhaps sphinx supports entities after all?