Google Groups no longer supports new Usenet posts or subscriptions. Historical content remains viewable.
Dismiss
Bug#932853: please someone "git checkout -b bullseye && git push"
6 views
Skip to first unread message
Tomas Pospisek
Jul 23, 2019, 6:40:02 PM7/23/19
to
Package: release-notes
Severity: wishlist
I have considered forking and branching via Salsa, and then sending the
pull request, but that's not less work. So I'm very kindly asking, if
someone with commit rights could please do a
git checkout -b bullseye && git push
So other then can maybe start forking on that branch and sending
patches/pull requests for already coming in bullseye changes:
#841666, #931785, #932580
Gracias,
*t
-- System Information:
Debian Release: 10.0
APT prefers stable
APT policy: (500, 'stable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386
Kernel: Linux 4.19.0-5-amd64 (SMP w/8 CPU cores)
Locale: LANG=de_CH.utf8, LC_CTYPE=de_CH.utf8 (charmap=UTF-8), LANGUAGE=de_CH:de (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Severity: wishlist
I have considered forking and branching via Salsa, and then sending the
pull request, but that's not less work. So I'm very kindly asking, if
someone with commit rights could please do a
git checkout -b bullseye && git push
So other then can maybe start forking on that branch and sending
patches/pull requests for already coming in bullseye changes:
#841666, #931785, #932580
Gracias,
*t
-- System Information:
Debian Release: 10.0
APT prefers stable
APT policy: (500, 'stable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386
Kernel: Linux 4.19.0-5-amd64 (SMP w/8 CPU cores)
Locale: LANG=de_CH.utf8, LC_CTYPE=de_CH.utf8 (charmap=UTF-8), LANGUAGE=de_CH:de (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Paul Gevers
Jul 24, 2019, 2:30:02 AM7/24/19
to
Control: owner -1 !
Hi Tomas,
Thanks a lot that you already want to start working on the bullseye
release-notes.
On 24-07-2019 00:33, Tomas Pospisek wrote:
> I have considered forking and branching via Salsa, and then sending the
> pull request, but that's not less work. So I'm very kindly asking, if
> someone with commit rights could please do a
>
> git checkout -b bullseye && git push
>
> So other then can maybe start forking on that branch and sending
> patches/pull requests for already coming in bullseye changes:
>
> #841666, #931785, #932580
I would wait with bugs like 841666 until it's clear that we actually
want that (at that time). And for bug 932580 it's too early to know what
should be in the text, so we should really defer that to later in the cycle.
That said, I want to prepare a proper branch (with some reworking and
some pruning), so I'll do just this, but not right *now* (there's other
stuff higher on my TODO list). Please, feel free to already propose
text, as that is the hardest part of nearly all release-note bugs.
Paul
Hi Tomas,
Thanks a lot that you already want to start working on the bullseye
release-notes.
On 24-07-2019 00:33, Tomas Pospisek wrote:
> I have considered forking and branching via Salsa, and then sending the
> pull request, but that's not less work. So I'm very kindly asking, if
> someone with commit rights could please do a
>
> git checkout -b bullseye && git push
>
> So other then can maybe start forking on that branch and sending
> patches/pull requests for already coming in bullseye changes:
>
> #841666, #931785, #932580
want that (at that time). And for bug 932580 it's too early to know what
should be in the text, so we should really defer that to later in the cycle.
That said, I want to prepare a proper branch (with some reworking and
some pruning), so I'll do just this, but not right *now* (there's other
stuff higher on my TODO list). Please, feel free to already propose
text, as that is the hardest part of nearly all release-note bugs.
Paul
Andrei POPESCU
Jul 24, 2019, 3:40:02 PM7/24/19
to
On Mi, 24 iul 19, 08:25:01, Paul Gevers wrote:
>
> That said, I want to prepare a proper branch (with some reworking and
> some pruning), so I'll do just this, but not right *now* (there's other
> stuff higher on my TODO list). Please, feel free to already propose
> text, as that is the hardest part of nearly all release-note bugs.
I would like to use this opportunity to propose that for bullseye the
>
> That said, I want to prepare a proper branch (with some reworking and
> some pruning), so I'll do just this, but not right *now* (there's other
> stuff higher on my TODO list). Please, feel free to already propose
> text, as that is the hardest part of nearly all release-note bugs.
Release Notes should be switched from DocBookXML to reStructuredText.
Reasons:
1. Easier to write due to the lighter markup
2. Easier to translate due to the lighter markup
There are entire strings where translators have to navigate between
the markup.
3. Modern toolchain
4. Transition recently done by Debian Policy and Developer's Reference
While the Release Notes do have significantly more translations,
large parts of it are not reusable between releases.
Kind regards,
Andrei
--
http://wiki.debian.org/FAQsFromDebianUser
Paul Gevers
Jul 24, 2019, 4:10:02 PM7/24/19
to
Hi,
On 24-07-2019 21:31, Andrei POPESCU wrote:
> I would like to use this opportunity to propose that for bullseye the
> Release Notes should be switched from DocBookXML to reStructuredText.
I don't think I disagree, as I though about this myself already, but I
don't have the energy to drive this. However, if there are volunteers, I
*think* I welcome this. (As long as translations are saved as much as
possible).
Paul
On 24-07-2019 21:31, Andrei POPESCU wrote:
> I would like to use this opportunity to propose that for bullseye the
> Release Notes should be switched from DocBookXML to reStructuredText.
don't have the energy to drive this. However, if there are volunteers, I
*think* I welcome this. (As long as translations are saved as much as
possible).
Paul
Osamu Aoki
Jul 25, 2019, 9:50:03 AM7/25/19
to
Hi,
On Thu, Jul 25, 2019 at 09:39:12AM +0300, Andrei POPESCU wrote:
> Control: clone -1 -2
> Control: severity -2 wishlist
> Control: retitle -2 Please migrate Release Notes to reStructuredText
>
> On Mi, 24 iul 19, 22:08:04, Paul Gevers wrote:
> > Hi,
> >
> > On 24-07-2019 21:31, Andrei POPESCU wrote:
> > > I would like to use this opportunity to propose that for bullseye the
> > > Release Notes should be switched from DocBookXML to reStructuredText.
> >
> > I don't think I disagree, as I though about this myself already, but I
> > don't have the energy to drive this. However, if there are volunteers, I
> > *think* I welcome this. (As long as translations are saved as much as
> > possible).
Yes. It can be done. I just converted developers-reference and someone
merged it ti main ;-)
If you follow my commit history, all tools and tricks are there.
https://salsa.debian.org/debian/developers-reference
I will work on build script more to make web page looks better. But
source conversion was possible though it is non-trivial.
> Ok, I'll have a look at it, though I wouldn't mind if someone is faster
> ;)
https://salsa.debian.org/debian/developers-reference/blob/1b0940a5c2879a5be3100b0e0f2bee6c5de58bdf/README.rst
This describes general tasks involved.
If someone makes broken PO file by copying some msgstr from random
msgstr, then conversion doesn't work well and it may be cryptic to
debug.
Regards,
Osamu
On Thu, Jul 25, 2019 at 09:39:12AM +0300, Andrei POPESCU wrote:
> Control: clone -1 -2
> Control: severity -2 wishlist
> Control: retitle -2 Please migrate Release Notes to reStructuredText
>
> On Mi, 24 iul 19, 22:08:04, Paul Gevers wrote:
> > Hi,
> >
> > On 24-07-2019 21:31, Andrei POPESCU wrote:
> > > I would like to use this opportunity to propose that for bullseye the
> > > Release Notes should be switched from DocBookXML to reStructuredText.
> >
> > I don't think I disagree, as I though about this myself already, but I
> > don't have the energy to drive this. However, if there are volunteers, I
> > *think* I welcome this. (As long as translations are saved as much as
> > possible).
merged it ti main ;-)
If you follow my commit history, all tools and tricks are there.
https://salsa.debian.org/debian/developers-reference
I will work on build script more to make web page looks better. But
source conversion was possible though it is non-trivial.
> Ok, I'll have a look at it, though I wouldn't mind if someone is faster
> ;)
This describes general tasks involved.
If someone makes broken PO file by copying some msgstr from random
msgstr, then conversion doesn't work well and it may be cryptic to
debug.
Regards,
Osamu
Paul Gevers
Dec 1, 2019, 2:40:03 PM12/1/19
to
Hi Andrei,
On Thu, 25 Jul 2019 22:44:29 +0900 Osamu Aoki <os...@debian.org> wrote:
> Yes. It can be done. I just converted developers-reference and someone
> merged it ti main ;-)
>
> If you follow my commit history, all tools and tricks are there.
>
> https://salsa.debian.org/debian/developers-reference
>
> I will work on build script more to make web page looks better. But
> source conversion was possible though it is non-trivial.
>
> > Ok, I'll have a look at it, though I wouldn't mind if someone is faster
> > ;)
>
> https://salsa.debian.org/debian/developers-reference/blob/1b0940a5c2879a5be3100b0e0f2bee6c5de58bdf/README.rst
>
> This describes general tasks involved.
>
> If someone makes broken PO file by copying some msgstr from random
> msgstr, then conversion doesn't work well and it may be cryptic to
> debug.
Are you still upto doing this change? I'm not expecting you worked on
this recently, but now is a good time to get this on the rails. Should
we first branch bullseye (bug #932853), make the relatively small fixes
there and then work on that branch or do you have a different proposal?
Paul
On Thu, 25 Jul 2019 22:44:29 +0900 Osamu Aoki <os...@debian.org> wrote:
> Yes. It can be done. I just converted developers-reference and someone
> merged it ti main ;-)
>
> If you follow my commit history, all tools and tricks are there.
>
> https://salsa.debian.org/debian/developers-reference
>
> I will work on build script more to make web page looks better. But
> source conversion was possible though it is non-trivial.
>
> > Ok, I'll have a look at it, though I wouldn't mind if someone is faster
> > ;)
>
> https://salsa.debian.org/debian/developers-reference/blob/1b0940a5c2879a5be3100b0e0f2bee6c5de58bdf/README.rst
>
> This describes general tasks involved.
>
> If someone makes broken PO file by copying some msgstr from random
> msgstr, then conversion doesn't work well and it may be cryptic to
> debug.
this recently, but now is a good time to get this on the rails. Should
we first branch bullseye (bug #932853), make the relatively small fixes
there and then work on that branch or do you have a different proposal?
Paul
Andrei POPESCU
Dec 1, 2019, 6:40:04 PM12/1/19
to
assuming I find the time for it.
In any case, if someone else is interested please go for it.
Regarding branches, wouldn't it make more sense to create a buster
branch and continue work on master? Just asking, I'm fine either way.
Paul Gevers
Dec 2, 2019, 4:20:03 PM12/2/19
to
Control: tags -1 pending
Hi,
On 24-07-2019 00:33, Tomas Pospisek wrote:
release notes from the buster branch I just created and pushed. Please
wait with making bullseye changes to the master branch until the request
is merged. I intent to upload the first changes with some clean-up,
which is hopefully helpful for the restructuring as there should be less
to restructure.
Paul
[1] https://salsa.debian.org/webmaster-team/cron/merge_requests/4
Hi,
On 24-07-2019 00:33, Tomas Pospisek wrote:
> Package: release-notes
> Severity: wishlist
>
> I have considered forking and branching via Salsa, and then sending the
> pull request, but that's not less work. So I'm very kindly asking, if
> someone with commit rights could please do a
>
> git checkout -b bullseye && git push
>
> So other then can maybe start forking on that branch and sending
> patches/pull requests for already coming in bullseye changes:
>
> #841666, #931785, #932580
I have requested [1] the webmaster-team to start building the buster
> Severity: wishlist
>
> I have considered forking and branching via Salsa, and then sending the
> pull request, but that's not less work. So I'm very kindly asking, if
> someone with commit rights could please do a
>
> git checkout -b bullseye && git push
>
> So other then can maybe start forking on that branch and sending
> patches/pull requests for already coming in bullseye changes:
>
> #841666, #931785, #932580
release notes from the buster branch I just created and pushed. Please
wait with making bullseye changes to the master branch until the request
is merged. I intent to upload the first changes with some clean-up,
which is hopefully helpful for the restructuring as there should be less
to restructure.
Paul
[1] https://salsa.debian.org/webmaster-team/cron/merge_requests/4
Paul Gevers
Dec 3, 2019, 3:40:03 PM12/3/19
to
Hi Andrei,
On 02-12-2019 00:29, Andrei POPESCU wrote:
> As mentioned before, this is something I would be interested to work on,
> assuming I find the time for it.
Ack.
> In any case, if someone else is interested please go for it.
>
> Regarding branches, wouldn't it make more sense to create a buster
> branch and continue work on master? Just asking, I'm fine either way.
Of course, that's what I meant. I did that in the mean time and master
is now free to start working on this transition to reStructeredText.
Paul
On 02-12-2019 00:29, Andrei POPESCU wrote:
> As mentioned before, this is something I would be interested to work on,
> assuming I find the time for it.
> In any case, if someone else is interested please go for it.
>
> Regarding branches, wouldn't it make more sense to create a buster
> branch and continue work on master? Just asking, I'm fine either way.
is now free to start working on this transition to reStructeredText.
Paul
Holger Wansing
May 18, 2023, 4:50:06 PM5/18/23
to
[[ debian-devel in CC, to get a wider audience regarding reStructuredText ]]
Hi,
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/
while the git repo containing the migration is at
https://salsa.debian.org/holgerw/release-notes
However, I may have some objections against the migration at all:
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.
In docbook speach these were entities, and you could use them in URLs like this:
Please follow the instructions in the <ulink
url="https://www.debian.org/releases/&oldreleasename;/releasenotes">Release
Notes for &debian; &oldrelease;</ulink> to upgrade to &debian;
&oldrelease; first if needed.
Please note the &oldreleasename; in the URL!
I could not get this working with sphinx (if someone knows better, please
contact me!)
In sphinx, I used hardcoded codenames like
https://www.debian.org/releases/bullseye/releasenotes instead, which means,
that there is much work to do to make the release-notes fit for the next release,
while with docbook you only need to change the entity in one place !!!
In sphinx you need to change every single occurence, and don't forget the
translations !!!
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.
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.
However, there is no package "release-notes" in the archive, so currently
it is only a matter of building it on wolkenstein for www.debian.org, right?
Regards
Holger
--
Holger Wansing <hwan...@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Hi,
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/
while the git repo containing the migration is at
https://salsa.debian.org/holgerw/release-notes
However, I may have some objections against the migration at all:
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.
In docbook speach these were entities, and you could use them in URLs like this:
Please follow the instructions in the <ulink
url="https://www.debian.org/releases/&oldreleasename;/releasenotes">Release
Notes for &debian; &oldrelease;</ulink> to upgrade to &debian;
&oldrelease; first if needed.
Please note the &oldreleasename; in the URL!
I could not get this working with sphinx (if someone knows better, please
contact me!)
In sphinx, I used hardcoded codenames like
https://www.debian.org/releases/bullseye/releasenotes instead, which means,
that there is much work to do to make the release-notes fit for the next release,
while with docbook you only need to change the entity in one place !!!
In sphinx you need to change every single occurence, and don't forget the
translations !!!
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.
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.
However, there is no package "release-notes" in the archive, so currently
it is only a matter of building it on wolkenstein for www.debian.org, right?
Regards
Holger
--
Holger Wansing <hwan...@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Richard Lewis
May 18, 2023, 8:10:05 PM5/18/23
to
On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwan...@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
> 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/
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
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.
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?
Laura Arjona Reina
May 19, 2023, 3:52:04 AM5/19/23
to
Hello
We have an open bug related to creating a Debian theme for the
documentation that uses Sphinx:
#915583 debian-policy: More attractive sphinx theme, please
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=915583
Unfortunately I think nobody could put on time on this yet.
Other bugs related to Sphinx in Debian documentation that may need to be
taken into account:
#987943 www.debian.org: Developers Reference: Sphinx search
non-functional: searchindex.js missing
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=987943
#1026446
Static javascript resources for Policy and DevRef give 404 errors,
breaking search
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1026446
Kind regards,
El 19/5/23 a las 1:58, Richard Lewis escribió:
--
Laura Arjona Reina
https://wiki.debian.org/LauraArjona
We have an open bug related to creating a Debian theme for the
documentation that uses Sphinx:
#915583 debian-policy: More attractive sphinx theme, please
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=915583
Unfortunately I think nobody could put on time on this yet.
Other bugs related to Sphinx in Debian documentation that may need to be
taken into account:
#987943 www.debian.org: Developers Reference: Sphinx search
non-functional: searchindex.js missing
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=987943
#1026446
Static javascript resources for Policy and DevRef give 404 errors,
breaking search
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1026446
Kind regards,
El 19/5/23 a las 1:58, Richard Lewis escribió:
Laura Arjona Reina
https://wiki.debian.org/LauraArjona
James Addison
May 19, 2023, 6:40:04 PM5/19/23
to
Followup-For: Bug #932957
X-Debbugs-Cc: hwan...@mailbox.org
Hi Holger,
> 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?
(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)
> 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?
Perhaps we can borrow some build scripting from developers-reference and/or
debian-policy.. but I suppose those don't have per-architecture output.
> 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)
Cheers,
James
[1] - https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
X-Debbugs-Cc: hwan...@mailbox.org
Hi Holger,
> Please note the &oldreleasename; in the URL!
> I could not get this working with sphinx (if someone knows better, please
> contact me!)
(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)
> 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.
know how the current docbook-based build varies by architecture?
Perhaps we can borrow some build scripting from developers-reference and/or
debian-policy.. but I suppose those don't have per-architecture output.
> 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.
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)
Cheers,
James
[1] - https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
RL
May 20, 2023, 8:10:06 AM5/20/23
to
James Addison <j...@jp-hosting.net> writes:
> (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)
Interesting idea, but who would use it - won't a release-notes package
> (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)
always be a whole release out of date?
(and the build-dependencies take a huge amount of disk space for
something you only read once a cycle, alhtough maybe sphinx fixes that)
Holger Wansing
May 20, 2023, 5:20:12 PM5/20/23
to
Hi,
Richard Lewis <richard.le...@googlemail.com> wrote (Fri, 19 May 2023 00:58:26 +0100):
> On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwan...@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).
Richard Lewis <richard.le...@googlemail.com> wrote (Fri, 19 May 2023 00:58:26 +0100):
> On Thu, 18 May 2023 22:39:11 +0200 Holger Wansing <hwan...@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
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"
"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?)
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)
> - 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
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
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
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.
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?
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
May 20, 2023, 5:42:01 PM5/20/23
to
Hi,
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 :-((
> > 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.
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?
> (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)
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 :-((
> > 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?
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.
> > 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)
Holger Wansing
May 21, 2023, 4:31:43 AM5/21/23
to
[[ Replying to two mails in one ]]
Hi,
Holger Wansing <hwan...@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.
Hi,
I fixed them, and updated the html files at
https://people.debian.org/~holgerw/release-notes_sphinx/
Hi,
Holger Wansing <hwan...@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 :-((
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.
https://people.debian.org/~holgerw/release-notes_sphinx/
James Addison
May 22, 2023, 6:50:05 PM5/22/23
to
On Sun, 21 May 2023 10:16:36 +0200, Holger wrote:
> There is also a problem using entities (or now called substitutions) in
> quoted lines like
> deb https://deb.debian.org/debian RELEASENAME main contrib
Ok, yep - I understand the problem there now, and have experimented with it a
> There is also a problem using entities (or now called substitutions) in
> quoted lines like
> deb https://deb.debian.org/debian RELEASENAME main contrib
bit locally. Roughly speaking: substitutions aren't possible within literal
quote blocks (there is a '::' a couple of lines before the mentioned line, and
adding the pipe '|' symbols around the substitution label doesn't make a
difference within literal blocks)
Not sure what to suggest yet as an alternative, though...
James Addison
May 22, 2023, 7:30:06 PM5/22/23
to
On Mon, 22 May 2023 23:40:46 +0100, James wrote:
> On Sun, 21 May 2023 10:16:36 +0200, Holger wrote:
> > There is also a problem using entities (or now called substitutions) in
> > quoted lines like
>
> > deb https://deb.debian.org/debian RELEASENAME main contrib
>
> Ok, yep - I understand the problem there now, and have experimented with it a
> bit locally. Roughly speaking: substitutions aren't possible within literal
> quote blocks (there is a '::' a couple of lines before the mentioned line, and
> adding the pipe '|' symbols around the substitution label doesn't make a
> difference within literal blocks)
It looks like the fix for that is to convert those literal ('::') blocks into
> On Sun, 21 May 2023 10:16:36 +0200, Holger wrote:
> > There is also a problem using entities (or now called substitutions) in
> > quoted lines like
>
> > deb https://deb.debian.org/debian RELEASENAME main contrib
>
> Ok, yep - I understand the problem there now, and have experimented with it a
> bit locally. Roughly speaking: substitutions aren't possible within literal
> quote blocks (there is a '::' a couple of lines before the mentioned line, and
> adding the pipe '|' symbols around the substitution label doesn't make a
> difference within literal blocks)
parsed-literal[1] ('.. parsed-literal::') blocks.
[1] - https://docutils.sourceforge.io/docs/ref/rst/directives.html#parsed-literal
Paul Gevers
May 23, 2023, 2:30:04 AM5/23/23
to
Hi Holger,
On 18-05-2023 22:39, Holger Wansing wrote:
> I worked on this recently, and I have something like a prototype ready.
Thanks a lot for working on this. I'm a bit swamped with last minute
things that need to happen before the release of bookworm, so I don't
expect to have time to look at this until after the release.
Paul
On 18-05-2023 22:39, Holger Wansing wrote:
> I worked on this recently, and I have something like a prototype ready.
things that need to happen before the release of bookworm, so I don't
expect to have time to look at this until after the release.
Paul
Holger Wansing
May 23, 2023, 11:52:14 AM5/23/23
to
Hi Paul,
As I wrote, I see this as a prototype, and thus I don't expected it to be a thing to
happen before releasing bookworm.
Holger
--
Sent from /e/ OS on Fairphone3
happen before releasing bookworm.
Holger
--
Sent from /e/ OS on Fairphone3
Holger Wansing
May 24, 2023, 5:10:05 PM5/24/23
to
Hi,
Yes, that works! Thanks for this!
I have therefore changed all literal ('::') blocks into parsed-literal
this way it's easier for future editors (no need to distinguish between
two different versions of quoted blocks).
Holger
I have therefore changed all literal ('::') blocks into parsed-literal
('.. parsed-literal::') blocks.
In output, there seems to be no difference (at least in this document), and
this way it's easier for future editors (no need to distinguish between
two different versions of quoted blocks).
Holger
Holger Wansing
May 24, 2023, 5:20:06 PM5/24/23
to
[ Sending this to #932957 as well, as it contains valueable info on that topic ]
Jeremy Stanley <fu...@yuggoth.org> wrote (Wed, 24 May 2023 18:22:09 +0000):
> On 2023-05-24 19:40:56 +0200 (+0200), Agathe Porte wrote:
> [...]
> > Maybe the idea was to introduce %OLD_RELEASE_NAME% and to call sed to
> > replace this kind of strings in a build step, and not rely on sphinx
> > substitution at all.
> >
> > I know that I have done this a few times and it works fine as a very
> > simple preprocessor.
>
> Similar things can be done at sphinx-build time with a custom Sphinx
> extension (can be a trivial Python module). We do that for the
> published security advisories list upstream in OpenStack:
>
> https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/conf.py#L31
>
> https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/_exts/vmt.py
>
> That's a more complex example because we generate a ton of content
> out of structured data (YAML) files by splatting the relevant fields
> into substitutions in a Jinja2 template, but for basic string
> substitution you could get away with something far simpler, or even
> use a canned one like (this was simply my first web search result):
>
> https://pypi.org/project/Sphinx-Substitution-Extensions/
>
> The examples in its readme look to be along the lines of the Debian
> Release Notes use case anyway. There's also basic substitutions
> support in the reStructuredText specification, which might be useful
> to reduce the amount of actual content you need to swap at build
> time:
>
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
The above seem related to the issue in question, but the solution pointed
out by James Addison in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932957#90
(use parsed-literal ('.. parsed-literal::') blocks)
seems to be the easier one (at least for this document) and it works fine
here. So I would go for it.
Thanks anyway
Jeremy Stanley <fu...@yuggoth.org> wrote (Wed, 24 May 2023 18:22:09 +0000):
> On 2023-05-24 19:40:56 +0200 (+0200), Agathe Porte wrote:
> [...]
> > Maybe the idea was to introduce %OLD_RELEASE_NAME% and to call sed to
> > replace this kind of strings in a build step, and not rely on sphinx
> > substitution at all.
> >
> > I know that I have done this a few times and it works fine as a very
> > simple preprocessor.
>
> Similar things can be done at sphinx-build time with a custom Sphinx
> extension (can be a trivial Python module). We do that for the
> published security advisories list upstream in OpenStack:
>
> https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/conf.py#L31
>
> https://opendev.org/openstack/ossa/src/commit/136b24c/doc/source/_exts/vmt.py
>
> That's a more complex example because we generate a ton of content
> out of structured data (YAML) files by splatting the relevant fields
> into substitutions in a Jinja2 template, but for basic string
> substitution you could get away with something far simpler, or even
> use a canned one like (this was simply my first web search result):
>
> https://pypi.org/project/Sphinx-Substitution-Extensions/
>
> The examples in its readme look to be along the lines of the Debian
> Release Notes use case anyway. There's also basic substitutions
> support in the reStructuredText specification, which might be useful
> to reduce the amount of actual content you need to swap at build
> time:
>
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions
The above seem related to the issue in question, but the solution pointed
out by James Addison in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=932957#90
(use parsed-literal ('.. parsed-literal::') blocks)
seems to be the easier one (at least for this document) and it works fine
here. So I would go for it.
Thanks anyway
James Addison
May 26, 2023, 8:11:51 AM5/26/23
to
Package: release-notes
Hi Holger,
I noticed one more problem with the output of the ReST release-notes:
Filtering of architecture-specific sections does not seem to be taking place,
so the 'Supported Architectures'[1] section for AMD64 currently contains the
text:
The ARCH-TITLE support (known as the Debian architecture amd64) now requires the “long NOP” instruction. Please refer to Baseline for 64-bit PC is now i686 for more information.
(the ARCH-TITLE placeholder is probably a small fixup - the problem I'd like
to draw attention to is the reference to 64-bit PC / amd64 as i686)
In the Docbook source, there is an 'arch="i386"' annotation[2] on the section's
XML element, so perhaps that is used to filter the content.
Cheers,
James
Stéphane Blondon
May 28, 2023, 7:30:05 AM5/28/23
to
> Richard Lewis <richard.le...@googlemail.com> wrote (Fri, 19 May 2023 00:58:26 +0100):
> > - 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?)
>
Sphinx uses Pygments to highlight source code. I guess no language is defined so Sphinx uses a wrong lexer. We should force Sphinx to use 'SourceListLexer' with:
.. code-block :: sources.list
Stéphane Blondon
May 28, 2023, 2:40:06 PM5/28/23
to
Le dim. 28 mai 2023 à 13:16, Stéphane Blondon
<stephane...@gmail.com> a écrit :
https://salsa.debian.org/holgerw/release-notes/-/merge_requests/2
<stephane...@gmail.com> a écrit :
> Sphinx uses Pygments to highlight source code. I guess no language is defined so Sphinx uses a wrong lexer. We should force Sphinx to use 'SourceListLexer' with:
> .. code-block :: sources.list
I sent a Merge Request on Holger's repository to implement it:
> .. code-block :: sources.list
https://salsa.debian.org/holgerw/release-notes/-/merge_requests/2
Holger Wansing
May 28, 2023, 4:42:31 PM5/28/23
to
Hi,
The highlighting feature is great, thanks for pointing this out!
However, we cannot use it here in most cases for sources.list entries,
since resolving substitutions does not work within such lines :-(
like in
But in many cases the highlighting gives us a great benefit, so I will
merge your MR and adapt the rare cases, where it does not work.
Thanks again!
Holger
However, we cannot use it here in most cases for sources.list entries,
since resolving substitutions does not work within such lines :-(
like in
But in many cases the highlighting gives us a great benefit, so I will
merge your MR and adapt the rare cases, where it does not work.
Thanks again!
Holger
Holger Wansing
May 28, 2023, 5:20:05 PM5/28/23
to
Hi,
James Addison <j...@jp-hosting.net> wrote (Fri, 26 May 2023 13:02:53 +0100):
> I noticed one more problem with the output of the ReST release-notes:
>
> Filtering of architecture-specific sections does not seem to be taking place,
> so the 'Supported Architectures'[1] section for AMD64 currently contains the
> text:
>
> The ARCH-TITLE support (known as the Debian architecture amd64) now requires the “long NOP” instruction. Please refer to Baseline for 64-bit PC is now i686 for more information.
>
> (the ARCH-TITLE placeholder is probably a small fixup - the problem I'd like
> to draw attention to is the reference to 64-bit PC / amd64 as i686)
>
> In the Docbook source, there is an 'arch="i386"' annotation[2] on the section's
> XML element, so perhaps that is used to filter the content.
Yes, filtering the content for the different architectures does not work yet.
That's one open point, where I have requested help for.
I have fixed the forgotten ARCH-TITLE placeholder now.
James Addison <j...@jp-hosting.net> wrote (Fri, 26 May 2023 13:02:53 +0100):
> I noticed one more problem with the output of the ReST release-notes:
>
> Filtering of architecture-specific sections does not seem to be taking place,
> so the 'Supported Architectures'[1] section for AMD64 currently contains the
> text:
>
> The ARCH-TITLE support (known as the Debian architecture amd64) now requires the “long NOP” instruction. Please refer to Baseline for 64-bit PC is now i686 for more information.
>
> (the ARCH-TITLE placeholder is probably a small fixup - the problem I'd like
> to draw attention to is the reference to 64-bit PC / amd64 as i686)
>
> In the Docbook source, there is an 'arch="i386"' annotation[2] on the section's
> XML element, so perhaps that is used to filter the content.
That's one open point, where I have requested help for.
I have fixed the forgotten ARCH-TITLE placeholder now.
James Addison
May 28, 2023, 7:31:25 PM5/28/23
to
Oops - there were a couple of problems with my most recent message here:
* Forgot to cc you on the details, Holger (in short summary: the ReST 'only'
directive[1] may be helpful here, and could be used with a '-t <tag>'
command-line option to sphinx-build from the Makefile)
* I didn't read the documentation! The tags for the 'only' directive must be
valid Python identifiers, so 'arch_i386' would work as a tag name, but
'arch-i386' (that I had suggested previously) would not.
[1] - https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags
* Forgot to cc you on the details, Holger (in short summary: the ReST 'only'
directive[1] may be helpful here, and could be used with a '-t <tag>'
command-line option to sphinx-build from the Makefile)
* I didn't read the documentation! The tags for the 'only' directive must be
valid Python identifiers, so 'arch_i386' would work as a tag name, but
'arch-i386' (that I had suggested previously) would not.
[1] - https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#including-content-based-on-tags
James Addison
May 28, 2023, 7:31:25 PM5/28/23
to
Package: release-notes
Followup-For: Bug #932957
Followup-For: Bug #932957
> Yes, filtering the content for the different architectures does not work yet.
Ah, and I said I would help with that :)
Although I don't yet know exactly how it's going to interact with the build
process, I _think_ that a feature we could use for this is the 'only'
directive:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-only
Although this could benefit from more thought, initially I suggest we adopt a
tag format something like 'arch-{debarch}' to handle this (so the conditional
clause here would be placed within a '.. only:: arch-i386' block.
From there, we could pass the corresponding tag on the commandline using the
'-t' option, I guess in the Makefile:
https://salsa.debian.org/holgerw/release-notes/-/blob/a2ba839790573915a80db75405abf8ef9212ac8e/Makefile#L103
Holger Wansing
May 29, 2023, 6:02:17 AM5/29/23
to
Hi,
James Addison <j...@jp-hosting.net> wrote (Mon, 29 May 2023 00:18:36 +0100):
> [[Holger Wansing wrote:]]
I have implemented such things now in
https://salsa.debian.org/holgerw/release-notes/-/commit/0304c87400432e1905d1bb04d39468a632876978
as a first step for arch-depending filtering.
Works so far, if the wanted arch is set in the Makefile (line 175) via the -t option.
Thanks for your help on this!
Now we just need an infrastructure, to loop over all architectures for build targets...
James Addison <j...@jp-hosting.net> wrote (Mon, 29 May 2023 00:18:36 +0100):
> [[Holger Wansing wrote:]]
https://salsa.debian.org/holgerw/release-notes/-/commit/0304c87400432e1905d1bb04d39468a632876978
as a first step for arch-depending filtering.
Works so far, if the wanted arch is set in the Makefile (line 175) via the -t option.
Thanks for your help on this!
Now we just need an infrastructure, to loop over all architectures for build targets...
Holger Wansing
Jun 2, 2023, 8:40:05 AM6/2/23
to
Some status update:
I managed to expand the Makefile, to build r-n for different archs for all
languages and for formats text+pdf+nopdf+html:
https://salsa.debian.org/holgerw/release-notes/-/commits/master?ref_type=heads
Open points:
- In this version, it builds for amd64+armel+i386+ppc64el only. No problem,
to expand this for more archs though.
- For now, I have separate conf.py files for the different archs, which I copy
in place before starting the builds; needs to be replaced by some sed mechanism.
- The list of archs is hardcoded in the Makefile for now.
- The target 'make install' is not ready; you can only build with
'make text|make pdf|make nopdf|make html|make all' and get the results in
the build dir.
I managed to expand the Makefile, to build r-n for different archs for all
languages and for formats text+pdf+nopdf+html:
https://salsa.debian.org/holgerw/release-notes/-/commits/master?ref_type=heads
Open points:
- In this version, it builds for amd64+armel+i386+ppc64el only. No problem,
to expand this for more archs though.
- For now, I have separate conf.py files for the different archs, which I copy
in place before starting the builds; needs to be replaced by some sed mechanism.
- The list of archs is hardcoded in the Makefile for now.
- The target 'make install' is not ready; you can only build with
'make text|make pdf|make nopdf|make html|make all' and get the results in
the build dir.
Stuart Prescott
Jun 3, 2023, 12:50:06 AM6/3/23
to
Hi Holger
Thanks for working on this :)
> - The list of archs is hardcoded in the Makefile for now.
The following might provide you with some useful way of not hard-coding
such information:
curl -s 'https://api.ftp-master.debian.org/suite/bookworm'
(pipe that into « jq -r '.architectures[]' » to get just the archs as
plain text)
You might want to make that a 'maintainer-run' step rather than is run
occasionally as part of preparing a release, rather than as a build time
step. That is, the maintainer runs that from a machine with internet
access to find the list of archs that should be used; this is then
cached in the repo until it is next refreshed. There is precedent for
this 'maintainer-run' step in various "make dist' mechanisms (from the
autotools world) and how the dh-python packages prepares a cache of
known python modules in the archive for later module→package translation.
There has been talk for a while about how we might avoid baking in
internal metadata in packages and there might be more inspiration on how
to do this in other parts of the project:
https://wiki.debian.org/SuitesAndReposExtension
(there are already a couple of entries there for the release notes)
cheers
Stuart
--
Stuart Prescott http://www.nanonanonano.net/ stu...@nanonanonano.net
Debian Developer http://www.debian.org/ stu...@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
Thanks for working on this :)
> - The list of archs is hardcoded in the Makefile for now.
such information:
curl -s 'https://api.ftp-master.debian.org/suite/bookworm'
(pipe that into « jq -r '.architectures[]' » to get just the archs as
plain text)
You might want to make that a 'maintainer-run' step rather than is run
occasionally as part of preparing a release, rather than as a build time
step. That is, the maintainer runs that from a machine with internet
access to find the list of archs that should be used; this is then
cached in the repo until it is next refreshed. There is precedent for
this 'maintainer-run' step in various "make dist' mechanisms (from the
autotools world) and how the dh-python packages prepares a cache of
known python modules in the archive for later module→package translation.
There has been talk for a while about how we might avoid baking in
internal metadata in packages and there might be more inspiration on how
to do this in other parts of the project:
https://wiki.debian.org/SuitesAndReposExtension
(there are already a couple of entries there for the release notes)
cheers
Stuart
--
Stuart Prescott http://www.nanonanonano.net/ stu...@nanonanonano.net
Debian Developer http://www.debian.org/ stu...@debian.org
GPG fingerprint 90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7
James Addison
Jun 3, 2023, 8:00:05 AM6/3/23
to
unarchive 977358
reopen 977358
blocks 977358 by 952450
Although this was documented for bullseye, the underlying cause
remains, and I think that it could be valuable for users to continue
to have this documentation available.
I've tested that the previously-added guidance from the bullseye
release notes remains valid and works on a bookworm system, and have
pushed a branch[1] to Salsa to restore the documentation.
Bugreport #952450 tracks a longer-term fix, and once that is resolved
I think it'd be fine to drop this note from the release-notes.
(for most other temporary/transitional release note issues, I think
it's fine to drop them between releases - this one seems to me like an
exception)
It's possible that this is too late to be included in the bookworm
release notes (and my apologies, if so). If not, though, I'll provide
a similar commit for the reStructuredText migration (cc'd).
[1] - https://salsa.debian.org/jayaddison/release-notes-docbook/-/tree/bug-977358/retain-issue-note
reopen 977358
blocks 977358 by 952450
Although this was documented for bullseye, the underlying cause
remains, and I think that it could be valuable for users to continue
to have this documentation available.
I've tested that the previously-added guidance from the bullseye
release notes remains valid and works on a bookworm system, and have
pushed a branch[1] to Salsa to restore the documentation.
Bugreport #952450 tracks a longer-term fix, and once that is resolved
I think it'd be fine to drop this note from the release-notes.
(for most other temporary/transitional release note issues, I think
it's fine to drop them between releases - this one seems to me like an
exception)
It's possible that this is too late to be included in the bookworm
release notes (and my apologies, if so). If not, though, I'll provide
a similar commit for the reStructuredText migration (cc'd).
[1] - https://salsa.debian.org/jayaddison/release-notes-docbook/-/tree/bug-977358/retain-issue-note
Holger Wansing
Jun 4, 2023, 9:20:05 AM6/4/23
to
Hi Stuart,
Stuart Prescott <stu...@debian.org> wrote (Sat, 3 Jun 2023 14:45:46 +1000):
> > - The list of archs is hardcoded in the Makefile for now.
>
> The following might provide you with some useful way of not hard-coding
> such information:
>
> curl -s 'https://api.ftp-master.debian.org/suite/bookworm'
>
> (pipe that into « jq -r '.architectures[]' » to get just the archs as
> plain text)
I managed to get a list of all relevant architectures via
curl -s 'https://api.ftp-master.debian.org/suite/testing' | jq -r '.architectures[]' | grep -v all | grep -v source
> You might want to make that a 'maintainer-run' step rather than is run
> occasionally as part of preparing a release, rather than as a build time
> step. That is, the maintainer runs that from a machine with internet
> access to find the list of archs that should be used; this is then
> cached in the repo until it is next refreshed. There is precedent for
> this 'maintainer-run' step in various "make dist' mechanisms (from the
> autotools world) and how the dh-python packages prepares a cache of
> known python modules in the archive for later module→package translation.
I created a prepare-release.sh script, which can be used to prepare the
release-notes for the next stable.
That script creates an archlist file, which holds the relevant archs for
the current testing.
Thanks for helping me with that!
> There has been talk for a while about how we might avoid baking in
> internal metadata in packages and there might be more inspiration on how
> to do this in other parts of the project:
>
> https://wiki.debian.org/SuitesAndReposExtension
>
> (there are already a couple of entries there for the release notes)
Shouldn't the above solution be added to that wiki page?
(I don't see it there, right?)
Stuart Prescott <stu...@debian.org> wrote (Sat, 3 Jun 2023 14:45:46 +1000):
> > - The list of archs is hardcoded in the Makefile for now.
>
> The following might provide you with some useful way of not hard-coding
> such information:
>
> curl -s 'https://api.ftp-master.debian.org/suite/bookworm'
>
> (pipe that into « jq -r '.architectures[]' » to get just the archs as
> plain text)
curl -s 'https://api.ftp-master.debian.org/suite/testing' | jq -r '.architectures[]' | grep -v all | grep -v source
> You might want to make that a 'maintainer-run' step rather than is run
> occasionally as part of preparing a release, rather than as a build time
> step. That is, the maintainer runs that from a machine with internet
> access to find the list of archs that should be used; this is then
> cached in the repo until it is next refreshed. There is precedent for
> this 'maintainer-run' step in various "make dist' mechanisms (from the
> autotools world) and how the dh-python packages prepares a cache of
> known python modules in the archive for later module→package translation.
release-notes for the next stable.
That script creates an archlist file, which holds the relevant archs for
the current testing.
Thanks for helping me with that!
> There has been talk for a while about how we might avoid baking in
> internal metadata in packages and there might be more inspiration on how
> to do this in other parts of the project:
>
> https://wiki.debian.org/SuitesAndReposExtension
>
> (there are already a couple of entries there for the release notes)
(I don't see it there, right?)
Paul Gevers
Jun 14, 2023, 3:31:18 PM6/14/23
to
Hi,
On 20-05-2023 23:26, Holger Wansing wrote:
>>> 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.
At the price this may have been answered already, I think the current
release notes are not packages because typically a lot of the relevant
changes get updated in the weeks *around* the release. So one would have
an outdated release notes. On top of that, most "issues to be aware of
while upgrading" won't be so useful if you already upgraded. Having said
that, I don't mind we make it a package, we just need to be clear of
what the purpose is inside a release.
Also, on the topic of arch-specific builds, I not convinced it's worth a
lot of effort. The amount of arch specific pieces is rather limited, so
I wouldn't mind if we drop that altogether. Currently, we don't do a
great service to people that need to support multiple architectures,
because they need to *search* for the delta's, so I wouldn't be
surprised if it is even better if we drop it.
Paul
On 20-05-2023 23:26, Holger Wansing wrote:
>>> 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.
release notes are not packages because typically a lot of the relevant
changes get updated in the weeks *around* the release. So one would have
an outdated release notes. On top of that, most "issues to be aware of
while upgrading" won't be so useful if you already upgraded. Having said
that, I don't mind we make it a package, we just need to be clear of
what the purpose is inside a release.
Also, on the topic of arch-specific builds, I not convinced it's worth a
lot of effort. The amount of arch specific pieces is rather limited, so
I wouldn't mind if we drop that altogether. Currently, we don't do a
great service to people that need to support multiple architectures,
because they need to *search* for the delta's, so I wouldn't be
surprised if it is even better if we drop it.
Paul
Holger Wansing
Jun 14, 2023, 4:00:04 PM6/14/23
to
Hi,
Paul Gevers <elb...@debian.org> wrote (Wed, 14 Jun 2023 21:19:00 +0200):
> Also, on the topic of arch-specific builds, I not convinced it's worth a
> lot of effort. The amount of arch specific pieces is rather limited, so
> I wouldn't mind if we drop that altogether. Currently, we don't do a
> great service to people that need to support multiple architectures,
> because they need to *search* for the delta's, so I wouldn't be
> surprised if it is even better if we drop it.
From the technical side, I managed to get the arch-specific builds done in
the meantime basically; so no problem anymore there - theoretically.
On the other side, I also thought about the arch-specific differences, and
given they are only rather small, my assumption was, that it's maybe not worth
it to differentiate between archs, when it comes to filtering out content
of r-n depending on the architecture.
But even if we leave that point out, there are some arch-dependent links like
http://mirrors.kernel.org/debian/dists/bookworm/main/binary-amd64/...
in chapter 4.3.1
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#network
So, we still need to build the release-notes differentiated by archs
(based on the current content).
However, that does not mean, we could not change our base rules, so that
filtering out chapters based on architecture is no longer used.
I would vote for this solution, yes.
Paul Gevers <elb...@debian.org> wrote (Wed, 14 Jun 2023 21:19:00 +0200):
> Also, on the topic of arch-specific builds, I not convinced it's worth a
> lot of effort. The amount of arch specific pieces is rather limited, so
> I wouldn't mind if we drop that altogether. Currently, we don't do a
> great service to people that need to support multiple architectures,
> because they need to *search* for the delta's, so I wouldn't be
> surprised if it is even better if we drop it.
the meantime basically; so no problem anymore there - theoretically.
On the other side, I also thought about the arch-specific differences, and
given they are only rather small, my assumption was, that it's maybe not worth
it to differentiate between archs, when it comes to filtering out content
of r-n depending on the architecture.
But even if we leave that point out, there are some arch-dependent links like
http://mirrors.kernel.org/debian/dists/bookworm/main/binary-amd64/...
in chapter 4.3.1
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#network
So, we still need to build the release-notes differentiated by archs
(based on the current content).
However, that does not mean, we could not change our base rules, so that
filtering out chapters based on architecture is no longer used.
I would vote for this solution, yes.
Holger Wansing
Jun 18, 2023, 8:40:04 AM6/18/23
to
Hi,
Thinking a bit more about this, I wonder if we could indeed get rid of
architecture-dependent r-n at all.
If all paragraphs/chapters are visible for all archs anyway, there are
only two situations where the arch shortname (amd64, i386 etc.) is used
in URLs. That is in
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#network
and
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#localmirror
<quote>
For example, suppose your closest Debian mirror is http://mirrors.kernel.org.
If you inspect that mirror with a web browser, you will notice that the main
directories are organized like this:
http://mirrors.kernel.org/debian/dists/bookworm/main/binary-amd64/...
http://mirrors.kernel.org/debian/dists/bookworm/contrib/binary-amd64/...
To configure APT to use a given mirror, add a line like this (again,
assuming you are using main and contrib):
deb http://mirrors.kernel.org/debian bookworm main contrib
</quote>
So, the arch-dependent directories on the mirrors are mentioned here, but the
arch part is not really relevant here. We could just skip the last part of
the URL and point to
http://mirrors.kernel.org/debian/dists/bookworm/main/..
and that's it. The same counts for the second occurrence of arch shortname.
That gives us the possibility, to simplify the whole r-n thing to only build
one generic release-notes variant for all archs, in the different languages,
and we are done.
How does that sound?
architecture-dependent r-n at all.
If all paragraphs/chapters are visible for all archs anyway, there are
only two situations where the arch shortname (amd64, i386 etc.) is used
in URLs. That is in
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#network
and
https://www.debian.org/releases/stable/amd64/release-notes/ch-upgrading.en.html#localmirror
<quote>
For example, suppose your closest Debian mirror is http://mirrors.kernel.org.
If you inspect that mirror with a web browser, you will notice that the main
directories are organized like this:
http://mirrors.kernel.org/debian/dists/bookworm/main/binary-amd64/...
http://mirrors.kernel.org/debian/dists/bookworm/contrib/binary-amd64/...
To configure APT to use a given mirror, add a line like this (again,
assuming you are using main and contrib):
deb http://mirrors.kernel.org/debian bookworm main contrib
</quote>
So, the arch-dependent directories on the mirrors are mentioned here, but the
arch part is not really relevant here. We could just skip the last part of
the URL and point to
http://mirrors.kernel.org/debian/dists/bookworm/main/..
and that's it. The same counts for the second occurrence of arch shortname.
That gives us the possibility, to simplify the whole r-n thing to only build
one generic release-notes variant for all archs, in the different languages,
and we are done.
How does that sound?
Paul Gevers
Jun 21, 2023, 4:31:39 AM6/21/23
to
Hi Holger,
On 18-06-2023 14:32, Holger Wansing wrote:
> We could just skip the last part of
> the URL and point to
> http://mirrors.kernel.org/debian/dists/bookworm/main/..
> and that's it.
I agree.
Paul
On 18-06-2023 14:32, Holger Wansing wrote:
> We could just skip the last part of
> the URL and point to
> http://mirrors.kernel.org/debian/dists/bookworm/main/..
> and that's it.
Paul
Holger Wansing
Jun 25, 2023, 8:20:05 AM6/25/23
to
Hi,
Holger Wansing <hwan...@mailbox.org> wrote (Sun, 18 Jun 2023 14:32:25 +0200):
> That gives us the possibility, to simplify the whole r-n thing to only build
> one generic release-notes variant for all archs, in the different languages,
> and we are done.
>
> How does that sound?
Status update:
1.
I have reduced the build chain to only build one generic arch-independent
variant of r-n, for all languages. It has all the content, and it's just named
"Release Notes for Debian 12 (bookworm)"
no longer mentioning any arch name in the title, and without any arch-name
reference in the whole document.
Note: If we decide to go with such approach, the website would need an
overhaul because of this!!!
2.
I added some sort of a basic-level draft mode:
Sphinx does not have support for a watermark, as dblatex had (at least not
in the sphinx version/packages we have in Debian; there is a contrib
extension 'sphinxmark' which does that, but that's not available in
Sphinx mainstream).
So I have just added a bold
"DRAFT MODE - in development for the next release"
on the html index page.
Maybe someone has better ideas?
AFAICS we could go forward with this via using a different html layout
template, or using a different theme, but I could not get that running.
The current version can still be found at
https://people.debian.org/~holgerw/release-notes_sphinx
for all languages and in html|text|pdf
(or grab the results from Salsa's CI at
https://salsa.debian.org/holgerw/release-notes/-/pipelines
which builds fine now.)
Holger Wansing <hwan...@mailbox.org> wrote (Sun, 18 Jun 2023 14:32:25 +0200):
> That gives us the possibility, to simplify the whole r-n thing to only build
> one generic release-notes variant for all archs, in the different languages,
> and we are done.
>
> How does that sound?
1.
I have reduced the build chain to only build one generic arch-independent
variant of r-n, for all languages. It has all the content, and it's just named
"Release Notes for Debian 12 (bookworm)"
no longer mentioning any arch name in the title, and without any arch-name
reference in the whole document.
Note: If we decide to go with such approach, the website would need an
overhaul because of this!!!
2.
I added some sort of a basic-level draft mode:
Sphinx does not have support for a watermark, as dblatex had (at least not
in the sphinx version/packages we have in Debian; there is a contrib
extension 'sphinxmark' which does that, but that's not available in
Sphinx mainstream).
So I have just added a bold
"DRAFT MODE - in development for the next release"
on the html index page.
Maybe someone has better ideas?
AFAICS we could go forward with this via using a different html layout
template, or using a different theme, but I could not get that running.
The current version can still be found at
https://people.debian.org/~holgerw/release-notes_sphinx
for all languages and in html|text|pdf
(or grab the results from Salsa's CI at
https://salsa.debian.org/holgerw/release-notes/-/pipelines
which builds fine now.)
Paul Gevers
Jun 25, 2023, 1:30:04 PM6/25/23
to
Hi Holger,
On 25-06-2023 14:11, Holger Wansing wrote:
> I have reduced the build chain to only build one generic arch-independent
> variant of r-n, for all languages. It has all the content, and it's just named
> "Release Notes for Debian 12 (bookworm)"
> no longer mentioning any arch name in the title, and without any arch-name
> reference in the whole document.
Great.
> Note: If we decide to go with such approach, the website would need an
> overhaul because of this!!!
Sure.
> I added some sort of a basic-level draft mode:
To be fair, I'm not very attached to it. During the previous release
(bullseye) I even had the notes in non-draft mode for (nearly) the whole
preparation period. I'm not sure anybody took the notes for something
they were not.
Paul
On 25-06-2023 14:11, Holger Wansing wrote:
> I have reduced the build chain to only build one generic arch-independent
> variant of r-n, for all languages. It has all the content, and it's just named
> "Release Notes for Debian 12 (bookworm)"
> no longer mentioning any arch name in the title, and without any arch-name
> reference in the whole document.
> Note: If we decide to go with such approach, the website would need an
> overhaul because of this!!!
> I added some sort of a basic-level draft mode:
(bullseye) I even had the notes in non-draft mode for (nearly) the whole
preparation period. I'm not sure anybody took the notes for something
they were not.
Paul
Holger Wansing
Jul 29, 2023, 3:40:05 PM7/29/23
to
Hi,
I have worked out the last big blocker for this migration now.
That is, to allow the build on wolkenstein, which is happening via the
parts/7release-notes script in webmaster-team/cron git repo.
I forked that repo and committed my changings there:
https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads
Tests were successful, the results can be found on
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/,
in the exact same structure as they would appear on the Debian website.
The release-notes dir
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/
holds the html files for all languages, but content negotiation does not
work there apparently; and the apache server does not show a file browser
view for that directory.
You can find German for example via
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.de.html
or Dutch via
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.nl.html
And remember, there is only one generic variant for all archs now!
The build process in 7releases-notes is now different between stable
and testing: stable is still on docbook, and testing is on sphinx/
reStructuredText.
So, when the time comes, we could create a bookworm branch for r-n,
migrate master to sphinx, and activate the build on wolkenstein for
master/trixie.
That way, we have a comfortable test time, to get everything ready
on the website (Note: there are changings to do on the website then),
while the r-n for trixie are not in public attention.
So long
I have worked out the last big blocker for this migration now.
That is, to allow the build on wolkenstein, which is happening via the
parts/7release-notes script in webmaster-team/cron git repo.
I forked that repo and committed my changings there:
https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads
Tests were successful, the results can be found on
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/,
in the exact same structure as they would appear on the Debian website.
The release-notes dir
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/
holds the html files for all languages, but content negotiation does not
work there apparently; and the apache server does not show a file browser
view for that directory.
You can find German for example via
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.de.html
or Dutch via
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/index.nl.html
And remember, there is only one generic variant for all archs now!
The build process in 7releases-notes is now different between stable
and testing: stable is still on docbook, and testing is on sphinx/
reStructuredText.
So, when the time comes, we could create a bookworm branch for r-n,
migrate master to sphinx, and activate the build on wolkenstein for
master/trixie.
That way, we have a comfortable test time, to get everything ready
on the website (Note: there are changings to do on the website then),
while the r-n for trixie are not in public attention.
So long
Richard Lewis
Jul 30, 2023, 7:00:05 AM7/30/23
to
Holger Wansing <hwan...@mailbox.org> writes:
> Tests were successful, the results can be found on
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/,
> in the exact same structure as they would appear on the Debian
> website.
nice - it looks like it's come on a long way from the previous version.
> Tests were successful, the results can be found on
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/,
> in the exact same structure as they would appear on the Debian
> website.
A couple of minor things in the content:
in [0] the '#' is meant to indicate 'run this as root', but the rst has
'.. code-block:: shell' so the commands are being formatted as a
comment.
in [1] the second para is dummy text that is commented out in the XML
version. In the rst 'source' (but not visible in the html) there are
also some odd chars around 'formal' (the quotes seems to be fine in the
sections above).
[1] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#things-to-do-post-upgrade-before-rebooting
in [2] there seems to be an extra space in the RH column in
'c a-certificates-java' (in the source there is a linebreak after the c)
[2] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#known-severe-bugs
(And
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/about.en.html#sources-for-this-document
will need an update! - as will the README in salsa)
Holger Wansing
Jul 30, 2023, 2:31:29 PM7/30/23
to
Hi,
Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 11:10:10 +0100):
> in [0] the '#' is meant to indicate 'run this as root', but the rst has
> '.. code-block:: shell' so the commands are being formatted as a
> comment.
Yes, there are different methods for including quoted material, and they are
somewhat tricky sometimes.
I may lack detailed experience on this, so need more details:
- What's the exact URL where you found this? (there was no such link as [0])
- What makes you think, that the commands are formatted as comment?
Is it the font color or what?
> in [1] the second para is dummy text that is commented out in the XML
> version.
This reST version of r-n is kind of a draft, so it's not as ready as it would
be when in publication mode. Such details slipped through, sorry.
> In the rst 'source' (but not visible in the html) there are
> also some odd chars around 'formal' (the quotes seems to be fine in the
> sections above).
Reason for this was: there were different quote signs used in those sections.
I changed “this” quotes into "this" ones. That solves the problem.
> [1] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#things-to-do-post-upgrade-before-rebooting
>
> in [2] there seems to be an extra space in the RH column in
> 'c a-certificates-java' (in the source there is a linebreak after the c)
Also fixed.
However, this section is also kind of a placeholder, it will get replaced
with a updated list. But fixing the format is a good idea nevertheless.
> [2] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#known-severe-bugs
>
> (And
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/about.en.html#sources-for-this-document
> will need an update! - as will the README in salsa)
For sure. I am aware of this.
Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 11:10:10 +0100):
> in [0] the '#' is meant to indicate 'run this as root', but the rst has
> '.. code-block:: shell' so the commands are being formatted as a
> comment.
somewhat tricky sometimes.
I may lack detailed experience on this, so need more details:
- What's the exact URL where you found this? (there was no such link as [0])
- What makes you think, that the commands are formatted as comment?
Is it the font color or what?
> in [1] the second para is dummy text that is commented out in the XML
> version.
be when in publication mode. Such details slipped through, sorry.
> In the rst 'source' (but not visible in the html) there are
> also some odd chars around 'formal' (the quotes seems to be fine in the
> sections above).
I changed “this” quotes into "this" ones. That solves the problem.
> [1] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#things-to-do-post-upgrade-before-rebooting
>
> in [2] there seems to be an extra space in the RH column in
> 'c a-certificates-java' (in the source there is a linebreak after the c)
However, this section is also kind of a placeholder, it will get replaced
with a updated list. But fixing the format is a good idea nevertheless.
> [2] https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#known-severe-bugs
>
> (And
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/about.en.html#sources-for-this-document
> will need an update! - as will the README in salsa)
Richard Lewis
Jul 30, 2023, 4:40:04 PM7/30/23
to
Holger Wansing <hwan...@mailbox.org> writes:
> Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 11:10:10 +0100):
> Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 11:10:10 +0100):
>> in [0] the '#' is meant to indicate 'run this as root', but the rst has
>> '.. code-block:: shell' so the commands are being formatted as a
>> comment.
>
>> '.. code-block:: shell' so the commands are being formatted as a
>> comment.
>
> Yes, there are different methods for including quoted material, and they are
> somewhat tricky sometimes.
>
> I may lack detailed experience on this, so need more details:
> - What's the exact URL where you found this? (there was no such link as [0])
> - What makes you think, that the commands are formatted as comment?
> Is it the font color or what?
sorry - it's the use of italic in eg '# apt-mark auto rsyslog'
> somewhat tricky sometimes.
>
> I may lack detailed experience on this, so need more details:
> - What's the exact URL where you found this? (there was no such link as [0])
> - What makes you think, that the commands are formatted as comment?
> Is it the font color or what?
https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#changes-to-system-logging
i found
https://stackoverflow.com/questions/16397794/how-to-show-terminal-shell-code-snippets-in-sphinx
which i think says that 'code-block:: console' might be better than
'code-block:: shell', but i may be misunderstanding that page
Holger Wansing
Jul 31, 2023, 6:10:05 AM7/31/23
to
Hi,
Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 21:32:36 +0100):
> sorry - it's the use of italic in eg '# apt-mark auto rsyslog'
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#changes-to-system-logging
>
>
> i found
> https://stackoverflow.com/questions/16397794/how-to-show-terminal-shell-code-snippets-in-sphinx
> which i think says that 'code-block:: console' might be better than
> 'code-block:: shell', but i may be misunderstanding that page
Yes, 'code-block:: console' indeed works fine for most occurrences.
So I unified
'code-block:: text'
'code-block:: shell'
'code-block:: shell-session'
to
'code-block:: console'
The only case where that doesn't work is, when substitutions are included.
They only work within '.. parsed-literal::' sadly :-(
Richard Lewis <richard.le...@googlemail.com> wrote (Sun, 30 Jul 2023 21:32:36 +0100):
> sorry - it's the use of italic in eg '# apt-mark auto rsyslog'
> https://people.debian.org/~holgerw/release-notes_sphinx/www.debian.org/releases/trixie/release-notes/issues.en.html#changes-to-system-logging
>
>
> i found
> https://stackoverflow.com/questions/16397794/how-to-show-terminal-shell-code-snippets-in-sphinx
> which i think says that 'code-block:: console' might be better than
> 'code-block:: shell', but i may be misunderstanding that page
So I unified
'code-block:: text'
'code-block:: shell'
'code-block:: shell-session'
to
'code-block:: console'
The only case where that doesn't work is, when substitutions are included.
They only work within '.. parsed-literal::' sadly :-(
Holger Wansing
Aug 26, 2023, 12:40:05 AM8/26/23
to
Hi,
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
Please note, that the webmaster-team/cron script has to be overworked,
to deal with the new reST format.
I have prepared that in
https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads
(as written above).
Rationale:
It is common for all documentation packages we have on www.debian/doc,
that the package itself creates files during package build, which do not
fit into the webpage system (main point: content negotiation).
To deal with this, someone from the ddp team has developed a script
(long ago; don't know by head who was this), that renames the files
to fit the webpage (basically this is about adding the language
extension). This is in webmaster-team/cron/parts/7doc.
With the old docbook release-notes, this has been dealed with directly
in the build script.
Now in the new reST world, I have basically copied the whole build
mechanism from the developers-reference as is, with the intention to
rely on the mechanism from the 7doc script mentioned above
(the 7doc script has been adapted explicitly for reST/sphinx).
The release-notes have always been a corner case when it comes to how
they were built, compared to all other docs:
the r-n are built from source explicitly for the website, while for all
the other documentation we just unpack their binary debian packages,
rename the files via 7doc and that's it.
This does not work for the r-n, because there is no Debian package existing
for them.
So the r-n are always a separate world.
Based on that, I have kept the 7doc mechanism separately too, copied into
the new 7release-notes.
Means the 7release-notes script from webmaster-team/cron git repo
gets extremely expanded, to copy (and adjust) the functionality from 7doc.
I have developed and tested this here locally, it should work fine.
So I have created a merge request to get this done for the website:
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
Best regards
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
>
> On 29-07-2023 21:29, Holger Wansing wrote:
> > I have worked out the last big blocker for this migration now.
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>
> I have just requested webmaster to switch the bookworm build from the
> On 29-07-2023 21:29, Holger Wansing wrote:
> > I have worked out the last big blocker for this migration now.
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
Please note, that the webmaster-team/cron script has to be overworked,
to deal with the new reST format.
I have prepared that in
https://salsa.debian.org/holgerw/cron/-/commits/master?ref_type=heads
(as written above).
Rationale:
It is common for all documentation packages we have on www.debian/doc,
that the package itself creates files during package build, which do not
fit into the webpage system (main point: content negotiation).
To deal with this, someone from the ddp team has developed a script
(long ago; don't know by head who was this), that renames the files
to fit the webpage (basically this is about adding the language
extension). This is in webmaster-team/cron/parts/7doc.
With the old docbook release-notes, this has been dealed with directly
in the build script.
Now in the new reST world, I have basically copied the whole build
mechanism from the developers-reference as is, with the intention to
rely on the mechanism from the 7doc script mentioned above
(the 7doc script has been adapted explicitly for reST/sphinx).
The release-notes have always been a corner case when it comes to how
they were built, compared to all other docs:
the r-n are built from source explicitly for the website, while for all
the other documentation we just unpack their binary debian packages,
rename the files via 7doc and that's it.
This does not work for the r-n, because there is no Debian package existing
for them.
So the r-n are always a separate world.
Based on that, I have kept the 7doc mechanism separately too, copied into
the new 7release-notes.
Means the 7release-notes script from webmaster-team/cron git repo
gets extremely expanded, to copy (and adjust) the functionality from 7doc.
I have developed and tested this here locally, it should work fine.
So I have created a merge request to get this done for the website:
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
Best regards
Holger Wansing
Sep 3, 2023, 5:20:05 PM9/3/23
to
Package: www.debian.org
Severity: normal
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
>
> On 29-07-2023 21:29, Holger Wansing wrote:
please consider MR13 in webmaster's cron repo:
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
Thanks
Severity: normal
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
>
> On 29-07-2023 21:29, Holger Wansing wrote:
> > I have worked out the last big blocker for this migration now.
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>
> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
Hey webmaster team,
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
please consider MR13 in webmaster's cron repo:
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
Thanks
Holger Wansing
Oct 4, 2023, 3:10:04 AM10/4/23
to
Package: www.debian.org
Severity: normal
[Re-send once more; first try one month ago did not make it into the BTS]
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
>
> On 29-07-2023 21:29, Holger Wansing wrote:
Severity: normal
[Re-send once more; first try one month ago did not make it into the BTS]
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> Hi Holger,
>
> On 29-07-2023 21:29, Holger Wansing wrote:
> > I have worked out the last big blocker for this migration now.
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>
> > That is, to allow the build on wolkenstein, which is happening via the
> > parts/7release-notes script in webmaster-team/cron git repo.
>
> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
Hey webmaster team,
please consider MR13 in webmaster's cron repo:
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
Thanks
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
Hey webmaster team,
please consider MR13 in webmaster's cron repo:
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
Thanks
Holger Wansing
Oct 4, 2023, 4:00:04 AM10/4/23
to
Created a new bug to track the MR
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
That is https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053445
https://salsa.debian.org/webmaster-team/cron/-/merge_requests/13
That is https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053445
Holger Wansing
Nov 13, 2023, 5:30:05 AM11/13/23
to
Hi,
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
Time for a status update:
Since the new release-notes itself are now being built on www-master (based
on Sphinx), some changings were needed for the webpage (currently
www.debian.org/releases/testing/releasenotes), because we no longer have
separate release-notes for the different release-archs.
I did that yesterday, let's say as a proposal.
Previously, there was some sort of black magic (or maybe it's perl),
which automatically creates a table with all architectures, languages,
and output formats of the r-n.
Changing this mechanism to leave out the architecture part is out of my
skills, but I managed to copy (and adapt) the logic which is being used in
the debian.org/doc part of the website, to generate the list of available
languages and formats for the different manuals there.
It looks fine IMO, and it also works. However new languages are not
displayed automatically, so compared to the old mechanism there might
be some handwork needed at some point (but rare I guess).
@webmaster, @release-team, @ddp-team: what do you think? Would this
proposal be acceptable to you for the new release-notes (trixie and later)?
Paul Gevers <elb...@debian.org> wrote (Thu, 24 Aug 2023 14:10:41 +0200):
> I have just requested webmaster to switch the bookworm build from the
> master branch to the bookworm branch [1]. After that request gets merged
> and deployed, I'd like you to publish your work in the master branch
> such that we can work from there (and see the results too [2]). Because
> in your worked we stopped making notes per architecture, we probably
> need to make further changes to the webmaster archive, but let's first
> build something.
Since the new release-notes itself are now being built on www-master (based
on Sphinx), some changings were needed for the webpage (currently
www.debian.org/releases/testing/releasenotes), because we no longer have
separate release-notes for the different release-archs.
I did that yesterday, let's say as a proposal.
Previously, there was some sort of black magic (or maybe it's perl),
which automatically creates a table with all architectures, languages,
and output formats of the r-n.
Changing this mechanism to leave out the architecture part is out of my
skills, but I managed to copy (and adapt) the logic which is being used in
the debian.org/doc part of the website, to generate the list of available
languages and formats for the different manuals there.
It looks fine IMO, and it also works. However new languages are not
displayed automatically, so compared to the old mechanism there might
be some handwork needed at some point (but rare I guess).
@webmaster, @release-team, @ddp-team: what do you think? Would this
proposal be acceptable to you for the new release-notes (trixie and later)?
Holger Wansing
Nov 22, 2023, 4:10:06 PM11/22/23
to
Hi again,
Holger Wansing <hwan...@mailbox.org> wrote (Mon, 13 Nov 2023 11:19:07 +0100):
> Time for a status update:
> Since the new release-notes itself are now being built on www-master (based
> on Sphinx), some changings were needed for the webpage (currently
> www.debian.org/releases/testing/releasenotes), because we no longer have
> separate release-notes for the different release-archs.
>
> I did that yesterday, let's say as a proposal.
>
> Previously, there was some sort of black magic (or maybe it's perl),
> which automatically creates a table with all architectures, languages,
> and output formats of the r-n.
> Changing this mechanism to leave out the architecture part is out of my
> skills, but I managed to copy (and adapt) the logic which is being used in
> the debian.org/doc part of the website, to generate the list of available
> languages and formats for the different manuals there.
>
> It looks fine IMO, and it also works. However new languages are not
> displayed automatically, so compared to the old mechanism there might
> be some handwork needed at some point (but rare I guess).
>
>
> @webmaster, @release-team, @ddp-team: what do you think? Would this
> proposal be acceptable to you for the new release-notes (trixie and later)?
And since there has been a call for a Debian theme for Sphinx (see
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549), a proposal
for that can be found at
https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/
(for those, who are uncomfortable with the greenish theme).
Holger Wansing <hwan...@mailbox.org> wrote (Mon, 13 Nov 2023 11:19:07 +0100):
> Time for a status update:
> Since the new release-notes itself are now being built on www-master (based
> on Sphinx), some changings were needed for the webpage (currently
> www.debian.org/releases/testing/releasenotes), because we no longer have
> separate release-notes for the different release-archs.
>
> I did that yesterday, let's say as a proposal.
>
> Previously, there was some sort of black magic (or maybe it's perl),
> which automatically creates a table with all architectures, languages,
> and output formats of the r-n.
> Changing this mechanism to leave out the architecture part is out of my
> skills, but I managed to copy (and adapt) the logic which is being used in
> the debian.org/doc part of the website, to generate the list of available
> languages and formats for the different manuals there.
>
> It looks fine IMO, and it also works. However new languages are not
> displayed automatically, so compared to the old mechanism there might
> be some handwork needed at some point (but rare I guess).
>
>
> @webmaster, @release-team, @ddp-team: what do you think? Would this
> proposal be acceptable to you for the new release-notes (trixie and later)?
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549), a proposal
for that can be found at
https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/
(for those, who are uncomfortable with the greenish theme).
Laura Arjona Reina
Nov 24, 2023, 5:00:06 AM11/24/23
to
Hello Holger
And since there has been a call for a Debian theme for Sphinx (see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549), a proposal for that can be found at https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ (for those, who are uncomfortable with the greenish theme).
I've had a quick look at the theme in https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ and looks very nice both in my computer and my phone, and I think it's a good improvement for the current theme. Thank you *very much*. I don't know which is the better way forward, maybe add a repo for the theme in the ddp-team umbrella, and then file a bug for every documentation manual using Sphinx, suggesting including it? I also know there are some other bugs related to Debian Documentation using Sphinx (search box, javascript-related issues) but it's hard for me to find an enough-long chunk of time to look at them, apologies. Kind regards, --
Laura Arjona Reina https://wiki.debian.org/LauraArjona
Holger Wansing
Nov 24, 2023, 9:30:05 AM11/24/23
to
Hi,
Am 24. November 2023 10:50:19 MEZ schrieb Laura Arjona Reina <lar...@debian.org>:
>I've had a quick look at the theme inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ and looks very nice both in my computer and my phone, and I think it's a good improvement for the current theme. Thank you *very much*.
set some configuration options in conf.py, to adapt some details. That's all.
So no need to create a new theme IMO.
Just set the appropriate options in the manual, and build it.
Holger
--
Sent from /e/ OS on Fairphone3
Am 24. November 2023 10:50:19 MEZ schrieb Laura Arjona Reina <lar...@debian.org>:
>I've had a quick look at the theme inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ and looks very nice both in my computer and my phone, and I think it's a good improvement for the current theme. Thank you *very much*.
>
>I don't know which is the better way forward, maybe add a repo for the theme in the ddp-team umbrella, and then file a bug for every documentation manual using Sphinx, suggesting including it?
I used the alabaster theme, which is the default theme in Sphinx, and
>I don't know which is the better way forward, maybe add a repo for the theme in the ddp-team umbrella, and then file a bug for every documentation manual using Sphinx, suggesting including it?
set some configuration options in conf.py, to adapt some details. That's all.
So no need to create a new theme IMO.
Just set the appropriate options in the manual, and build it.
Holger
--
Sent from /e/ OS on Fairphone3
Holger Wansing
Nov 24, 2023, 5:00:05 PM11/24/23
to
[ Re-sending message; first attempt from smartphone dropped some recipients, sorry ]
>I've had a quick look at the theme inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ and looks very nice both in my computer and my phone, and I think it's a good improvement for the current theme. Thank you *very much*.
>I've had a quick look at the theme inhttps://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/release-notes/ and looks very nice both in my computer and my phone, and I think it's a good improvement for the current theme. Thank you *very much*.
>
>I don't know which is the better way forward, maybe add a repo for the theme in the ddp-team umbrella, and then file a bug for every documentation manual using Sphinx, suggesting including it?
>I don't know which is the better way forward, maybe add a repo for the theme in the ddp-team umbrella, and then file a bug for every documentation manual using Sphinx, suggesting including it?
I used the alabaster theme, which is the default theme in Sphinx, and
set some configuration options in conf.py, to adapt some details. That's all.
So no need to create a new theme IMO.
Just set the appropriate options in the manual, and build it.
set some configuration options in conf.py, to adapt some details. That's all.
So no need to create a new theme IMO.
Just set the appropriate options in the manual, and build it.
Holger Wansing
Nov 24, 2023, 5:40:05 PM11/24/23
to
Holger Wansing <hwan...@mailbox.org> wrote (Fri, 24 Nov 2023 22:49:47 +0100):
> I used the alabaster theme, which is the default theme in Sphinx, and
> set some configuration options in conf.py, to adapt some details. That's all.
>
> So no need to create a new theme IMO.
>
> Just set the appropriate options in the manual, and build it.
is now visible on www.debian.org/releases/trixie/release-notes.
I noticed, that the links to the previous and next chapter at the top
and the bottom of the pages are missing.
Some research showed, that the reason for this is the sphinx version on
www-master, which is a bullseye system.
Starting with the sphinx version in bookworm, those links are supported.
So this will start working, when wolkenstein will get updated to bookworm.
Moreover, I changed the Debian logo to include the document name (here:
"Release-Notes"), to have that information available on every page of the
release-notes (at the top).
0 new messages