[[ Replying to two mails in one ]]
Hi,
Holger Wansing wrote (Sat, 20 May 2023 23:26:47 +0200):
> James Addison 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 '' | 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:
>
>
> Cloud installations
>
> The cloud team 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 wrote (Sat, 20 May 2023 23:10:59 +0200):
> Hi,
>
> Richard Lewis wrote (Fri, 19 May 2023
> 00:58:26 +0100):
> > On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing
> > 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/releas
