Bug#932957: #932957 Please migrate Release Notes to reStructuredText
Hi,
Richard Lewis <richard.lewis.debian@googlemail.com> wrote (Fri, 19 May 2023 00:58:26 +0100):
> On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwansing@mailbox.org> wrote:
> 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 copied style and font settings from developers-reference, another
document, which has been migrated recently from docbook to sphinx.
So I consider this as a quasi-standard at the moment.
I copied it by intent, to get a consistent look for all manuals generated
with sphinx.
We can work on that later on, as Laura already pointed out there is even
a bugreport for this.
So will ignore this for now here.
> - 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"
The first version I built with sphinx had version displayed
"release-notes 5.0.1" which confused me even more.
Therefore I changed that in the sense of "release-notes version 12 for
Debian release 12". Can still be changed in any way...
> - 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?)
I see this in other sphinx-generated manuals as well. So maybe a bug in sphinx?
Or a feature?
> - 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)
good catch, that should be changed - that's an easy one :-)
> - 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.
Seems to be the default in Sphinx? Currently I cannot see how I could change that.
> - https://people.debian.org/~holgerw/release-notes_sphinx/en/html/genindex.html
> is completely blank
Yes, I already noticed that too.
And it's the same for the debian-policy and the developers-reference...
Needs to be investigated.
> - not sure "show source" on the left is all that useful for readers
That's a feature of sphinx, I guess.
And if a reader finds an error, or wants to make a proposal for a change, he
can easily access the source code and provide a patch against this.
So that's a good feature!
> 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
I have removed several old files from the repo now, amongst others the dbk
files in en.
The new rst files for English are in ./source/ (default for sphinx AFAICT).
> > 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.
That will not work.
You cannot replace all 'bullseye' by 'bookworm'. There are places, where the
'bullseye' needs to stay. So that needs to be done selective one-by-one.
> 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?
Sure, in sphinx that's called "substitution" and I use it already very much in
this manual.
The point is, that they do not work in all situations, where they did in docbook
(at least this is my current state of knowledge).
Holger
--
Holger Wansing <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Reply to: