Re: Bug#932957: Please migrate Release Notes to reStructuredText
[[ Replying to two mails in one ]]
Hi,
Holger Wansing <hwansing@mailbox.org> wrote (Sat, 20 May 2023 23:26:47 +0200):
> James Addison <jay@jp-hosting.net> wrote (Fri, 19 May 2023 23:28:55 +0100):
> > > Please note the &oldreleasename; in the URL!
> > > I could not get this working with sphinx (if someone knows better, please
> > > contact me!)
> >
> > Could the 'extlinks' feature[1] of Sphinx be helpful to migrate those?
>
> Yes, thanks for the pointer! I used that now to get the manpage links fixed!
>
> > (it allows defining URL pattern aliases, so for example :oldreleasenotes: could
> > map to https://www.debian.org/releases/bullseye/releasenotes and :releasenotes:
> > could map to https://www.debian.org/releases/bookworm/releasenotes for D12)
> >
> > Parameters are supported too, and that could be useful for package-or-filepath
> > refs (re: grep -r '`.*<' source |grep -o '<https.*>' | sort | uniq -c |sort -n)
>
> The drawback is, it is not as flexible as the entities in docbook.
> For example, there is the following URL in this manual in docbook:
>
> &url-debian-mirror-eg;/debian/dists/&releasename;/main/binary-&architecture;/...
>
> You see, there are three entites in this URL!
> This seems to be not supported by extlinks :-((
I focused a bit too much on the URL front here.
There is also a problem using entities (or now called substitutions) in
quoted lines like
deb https://deb.debian.org/debian RELEASENAME main contrib
or
# script -t 2>~/upgrade-RELEASENAMEstep.time -a ~/upgrade-RELEASENAMEstep.script
These also do not work.
That's the biggest blocker in the upgrading chapter IMHO.
> > > 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.
> >
> > I'll try to take a look into that soon to see what I can find out. Do you
> > know how the current docbook-based build varies by architecture?
>
> There are some chapters, which are only visible for specific architectures, like
> in installing.dbk:
>
> <section id="cloud" arch="amd64;arm64;ppc64el" condition="fixme">
> <title>Cloud installations</title>
> <para>
> The <ulink url="&url-cloud-team;">cloud team</ulink> publishes
> Debian &releasename; for several popular cloud computing services
> including:
>
>
> > Perhaps we can borrow some build scripting from developers-reference and/or
> > debian-policy.. but I suppose those don't have per-architecture output.
>
> I think so, yes. That will be of no help, I fear...
>
> > > 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.
> >
> > It's possible I've misunderstood, but would be the goals here to be to get
> > the release-notes documentation built by CI, and also for it to be distributed
> > as a Debian package itself?
> >
> > (someone who knows more may correct me, but I think it would be great to have
> > the package available for install using apt in addition to the website)
>
> That was my first thought as well, yes.
Hi,
Holger Wansing <hwansing@mailbox.org> wrote (Sat, 20 May 2023 23:10:59 +0200):
> 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 :-)
I fixed them, and updated the html files at
https://people.debian.org/~holgerw/release-notes_sphinx/
> > - 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 Wansing <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Reply to: