[[ Replying to two mails in one ]]
Hi, Holger Wansing <hwans...@mailbox.org> wrote (Sat, 20 May 2023 23:26:47 +0200): > James Addison <j...@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 <hwans...@mailbox.org> wrote (Sat, 20 May 2023 23:10:59 +0200): > Hi, > > Richard Lewis <richard.lewis.deb...@googlemail.com> wrote (Fri, 19 May 2023 > 00:58:26 +0100): > > On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwans...@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 <hwans...@mailbox.org> PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076