single-page html of debian-policy to be revived?

[Holger Wansing]

Hi,

Sean Whitton  wrote (Sun, 14 Apr 2024 12:27:34 +0800):
> On Thu 11 Apr 2024 at 08:32am GMT, Holger Levsen wrote:
> 
> > On Thu, Apr 11, 2024 at 09:18:06AM +0200, Thomas Lange wrote:
> >> A single page html may be an additional option but there's already the
> >> single page txt version and the PDF. That's sufficient and I see no
> >> need in providing more formats of this manual.
> >>
> >> Therefore we can close this and I will close 877337.
> >
> > fwiw, I disagree with this conclusion. single page txt and pdf versions
> > are no replacements for single page html.
> 
> I agree, and still think we should be publishing the single page version.

1.
Currently, the package does not ship this version. So this would have to
be re-added there.

2.
There are pro's and con's for both the single-page and multi-page variants.
Thus the only possible way IMO is to ship both via www.d.o.
The developers-refererence also ships both already, so it would be consistent 
there.
To make the existing mechanism work, which finds both variants on the
web mirrors via webwml, the single-page html file needs to be named
debian-policy.html:
https://salsa.debian.org/webmaster-team/webwml/-/blob/master/english/doc/devel-manuals.defs?ref_type=heads
That needs to be dealed with in the package, just renaming the file does not 
work, since it would break all the internal links.
(Don't know how it worked in the past on the website with the file being named 
policy-1.html though.)

3.
There were several bugs (e.g. #873456, #876075, #879048) with the single-page
html version. Are they known to be solved now?
Sphinx has received much development in the past 7 years, so there may be a
chance to have them fixed ... (?)
To get an idea of where we stand, I have built latest version of debian-policy
with re-activated singlehtml variant (build via sbuild, so with latest Sphinx
version), made the copy-and-rename dance which happens on wolkenstein for 
publication on www.d.o and pushed the result at
https://people.debian.org/~holgerw/debian-policy-with-singlehtml/

The multi-page html is found via
https://people.debian.org/~holgerw/debian-policy-with-singlehtml/debian-policy/index.html

while single-page html is at
https://people.debian.org/~holgerw/debian-policy-with-singlehtml/debian-policy/policy-1.html


Could the Policy Editors team check, if everything is fine now, and if 
this should be published again?
At least there is still an issue with the footnotes, there are 16 occurrences
of #id1 for example... (search for "[1]" in policy-1.html).


So long
Holger


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Re: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Holger Wansing]

Hi,

Bill Allombert  wrote (Wed, 10 Apr 2024 
22:24:20 +0200):
> On Wed, Apr 10, 2024 at 09:33:50PM +0200, Holger Wansing wrote:
> > Hello www team and debian-policy editor team,
> > 
> > Note: apparently we have no alternative beside js, if we want full-text 
> > search for html output (single-page html could be a possible way, but 
> > that output format has been disabled due to various other issues).
> 
> Sorry, but why is this so hard to generate a single-page html ?
> debiandoc could do it. Using the browser intra-page search is always much
> easier/faster that using a search box.

I did not go deeper into this scenario, I just found 
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=877337
which includes a forward-backword-forward dance switching multiple
times between multi-page and single-page html variant requests.


Holger


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Re: #872944 www.debian.org: Remove JavaScript from Policy Manual published on web mirrors

[Holger Wansing]

Hello www team and debian-policy editor team,


in-line with activating the new html theme on our website I also
worked on the javascript front:

to make the html theme work on small screens (smartphones) the readthedocs.org
theme relies on javascript functionality, to display a sidebar with the table
of content only, when the device is in landscape direction resp. when the 
burger button is pressed.

The second javascript functionality is the full-text search.

I made all needed changings, to get the above functions work and they are doing 
fine now. See 

Please note, that I made use of javascript by intend, despite of this bug 
requesting to remove all js functionality.
This is because I wanted to find out,  what we need (aka which javascript 
packages) to make all the above mentioned functions work. 
Since I lack the skills to value this simply by studying source code and 
reading documentation, I had to test this in live to be sure.

The outcome of this is:
we need content of the javascript packages "libjs-sphinxdoc" and "libjs-jquery" 
existing in the manuals' path, to accomplish the above goals.

We need to decide now, if we want these functionality, when they require 
those javascript packages. 
Or if we skip such functionality.

Note: apparently we have no alternative beside js, if we want full-text 
search for html output (single-page html could be a possible way, but 
that output format has been disabled due to various other issues).

And being able to show/hide the sidebar on smartphones is a great benefit
when screen size is limited.


There are requests to not use js, but it has also been mentioned, that it
may be worth it enabling js, because of the relatively reduced amount of js 
use in sphinxdoc / jquery.
Note: I'm lacking skills to inspect source code, which other functions are
integrated in the doctools.js / jquery.js / searchtools.js / sphinx-highlight.js
scripts resp. what the functions I find there are doing exactly! 
Maybe someone can make a statement here?

I would like to mention another point:
it's a Browser functionality for decades to have the possibility to disable
use of JavaScript. So people who want to avoid any risk due to js, can or
will most probably have JavaScript disabled in the Browser settings anyway.


Please note, that this decision is not only for debian-policy, but for
all sphinx-based manuals on Debian website.
(I hope we don't make different decisions on this question for the 
various manuals we have. That would make the implentation once again
more difficult.)



What should be done now?


Holger

Bug#1064593: issue with Debian-style html theme for sphinx-based documents

[Holger Wansing]

Control: reassign 1064593 www.debian.org


Hi all,

Sean Whitton  wrote (Tue, 02 Apr 2024 10:11:39 +0800):
> Hello,
> 
> On Mon 01 Apr 2024 at 02:50pm +02, Holger Wansing wrote:
> 
> > I now tend to switch to another approach (also proposed similarly by Adam):
> >
> > instead of relying on the rtd-theme package in the default install path of 
> > the
> > package installed by DSA, I will use the infrastructure in 1ftpfiles and
> > 7doc of webmaster's cron repo, to (always) fetch the latest version of that
> > package (and two more packages, which the former depends on: 
> > fonts-font-awesome
> > and fonts-lato, to get the needed fonts) and unpack+copy them into
> > a dedicated path inside the www build tree.
> >
> > That path will be synced to the static www mirrors, and we can symlink
> > to it from the manuals.
> > (And the content of that path will automatically be kept up-to-date on
> > the unstable version of packages, so we don't get outdated/orphaned
> > copies of that packages in the isolated path.)
> > I want the unstable version of that packages here, since they need to
> > incorporate with the unstable version of the different manuals (like
> > debian-policy), and those packages are built by buildd, so unstable.
> >
> > How does that sound in the light of Debian guidelines and best practice?
> >
> > Is it ok, to have such "isolated copies" of packages as described above?
> >
> > I have not much experience in similar things, so I would like to get
> > some comments here, please.
> 
> I mean, it seems okay to me, but it's up to the web team really.

Yeah, that makes we aware of that this bug is now assigned to the wrong
package (this is no longer an issue on debian-policy side, but on
www.debian.org). 

Therefore, web team is most probably not aware at all of this specific issue.
So, I'm reassigning this bug to www.debian.org now.
And also debian-doc in CC, since in the past the doc/manuals part of
the website was somehow under responsibility of -doc people IIRC.



@web + doc teams:
We have (after more than 5 years) a new Debian-style html theme for 
sphinx-based 
documents, created by Stéphane Blondon based on a readthedocs.org theme.
It looks really good, and a preview of debian-policy with this theme can be 
seen here:
https://people.debian.org/~holgerw/new-rtd-sphinx-theme-for-debian/debian-policy/debian-policy/

However, getting this theme to work on the Debian website became more and more 
of a challenge these days/weeks.
An issue came up, which can be seen at Debian's website:
https://www.debian.org/doc/debian-policy/
The html layout is completely broken, because the theme relys on files
provided by the sphinx-rtd-theme-common package, which are not there on
the www mirrors.
Getting that files correctly on the mirrors occured to become difficult, sadly.

You can find a current summary of this issue at
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1064593#125

This comes down to one more adaption of the 1ftpfiles / 7doc scripts
in webmaster's cron repo.
Attached is the latest version of my patch, to get this going.

It works so far, but I wonder if this is the way we want to go.
There is a significant amount of things, which need to work correctly to
make this new theme appear correctly on Debian's website:

We need a separate copy of 3 packages in our www build tree on
wolkenstein and all www static mirrors (simply let DSA install those
packages on the machines will not work).
And every sphinx-based manual needs relative symlinks in its tree, pointing
to the above packages' content.
The 1ftpfiles and 7doc scripts, which need to be adapted for that, and
also the situation on the www mirrors is getting more complex, so I'm unsure 
if we want this.
See my patch.

On the other side, I don't see any other solution apart from developing
a new theme.


Comments?


Holger


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/parts/1ftpfiles b/parts/1ftpfiles
index 3a2d953..3079131 100755
--- a/parts/1ftpfiles
+++ b/parts/1ftpfiles
@@ -72,6 +72,11 @@ $WGET -O - $httpurlamd64 | xzcat >Packages-amd64
 
 httpurlrepo="http://${ftpsite}/debian;
 
+# readthedocs.org html theme files and related fonts
+getdeb all sphinx-rtd-theme-common
+getdeb all fonts-font-awesome
+getdeb all fonts-lato
+
 # many language specific binary packages (arch=all)
 getdebs aptitude
 getdebs debian-faq
diff --git a/parts/7doc b/parts/7doc
index b079aea..c2ff284 100755
--- a/parts/7doc
+++ b/parts/7doc
@@ -341,6 +341,39 @@ if [ "$lang" = "en" ]; then
 fi
 }
 
+#
+
+place_symlinks_to_theme_files()
+# To make the html theme (which is based on a readthedocs.org theme) for
+# sphinx-base

Bug#1064593: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks

[Holger Wansing]

Hi,

Sean Whitton  wrote (Thu, 28 Mar 2024 09:48:51 +0800):
> Many thanks all for working on this, especially you Holger for this
> scripting work.  So, we're waiting in DSA and then on your script
> changes, and it'll work again.

DSA (adsb) did install the python3-sphinx-rtd-theme package on the www static 
mirrors (thanks Adam for the quick reaction !!!), and I pushed my changings 
to the 7doc script, but reality has proven me wrong, sadly:

The idea was, to have absolute symlinks from inside the manuals directories
to /usr/share/sphinx_rtd_theme/static/... and all looks fine on wolkenstein,
but those symlinks fail to get synced to the www static mirrors, because of
rsync's "--safe-links" option:

--safe-links ignore symlinks that point outside the tree

Thus, the debian-policy is still broken on our website, as before.


I now tend to switch to another approach (also proposed similarly by Adam):

instead of relying on the rtd-theme package in the default install path of the
package installed by DSA, I will use the infrastructure in 1ftpfiles and 
7doc of webmaster's cron repo, to (always) fetch the latest version of that 
package (and two more packages, which the former depends on: fonts-font-awesome
and fonts-lato, to get the needed fonts) and unpack+copy them into
a dedicated path inside the www build tree.

That path will be synced to the static www mirrors, and we can symlink
to it from the manuals.
(And the content of that path will automatically be kept up-to-date on
the unstable version of packages, so we don't get outdated/orphaned
copies of that packages in the isolated path.)
I want the unstable version of that packages here, since they need to
incorporate with the unstable version of the different manuals (like
debian-policy), and those packages are built by buildd, so unstable.

How does that sound in the light of Debian guidelines and best practice?

Is it ok, to have such "isolated copies" of packages as described above?

I have not much experience in similar things, so I would like to get
some comments here, please.

Or do people prefer a complete different way, like using another theme
or whatever? (since this thing is getting bigger and bigger currently)

(Please keep in mind that this is not only for debian-policy, but in the
long term all sphinx-based manuals are supposed to follow the path 
discussed here.)

I already proposed to switch away from dh_sphinxdoc, to completely get rid 
of this symlink issue, but someone mentioned various privacy issues as a
contra argument...



Patch attached for the first part (to get above mentioned packages
in the www build path) - just posted for reference here.
(Second part - to point the debian-policy manual to that path - will
follow in another round.)


Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/parts/1ftpfiles b/parts/1ftpfiles
index 3a2d953..3079131 100755
--- a/parts/1ftpfiles
+++ b/parts/1ftpfiles
@@ -72,6 +72,11 @@ $WGET -O - $httpurlamd64 | xzcat >Packages-amd64
 
 httpurlrepo="http://${ftpsite}/debian;
 
+# readthedocs.org html theme files and related fonts
+getdeb all sphinx-rtd-theme-common
+getdeb all fonts-font-awesome
+getdeb all fonts-lato
+
 # many language specific binary packages (arch=all)
 getdebs aptitude
 getdebs debian-faq
diff --git a/parts/7doc b/parts/7doc
index 6998512..47e076e 100755
--- a/parts/7doc
+++ b/parts/7doc
@@ -428,6 +428,45 @@ echo -n "Installing documents:" >> $webdocdir/build.log
 # We only have sid now
 dist=sid
 
+# readthedocs.org html theme files and related fonts.
+# We need those files inside the www.d.o build tree on wolkenstein, because
+# the manuals will have symlinks pointing to those files, and syncing such
+# symlinks to the static www mirrors fails, when they point outside of the
+# tree (because of rsync's "--safe-links" option).
+# Therefore, we cannot simply have the packages installed by DSA on
+# wolkenstein, but we need an own copy inside the tree (in
+# www/doc/html-theme).
+# Since the manuals here are built on buildds and therefore are based on
+# unstable, I want to use the unstable version of the following packages
+# as well.
+unpack sphinx-rtd-theme-common
+   for themefilecss in usr/share/sphinx_rtd_theme/static/css/* ; do
+	mkdirp $webdocdir/html-theme/sphinx_rtd_theme/static/css
+	cp -rf $themefilecss $webdocdir/html-theme/sphinx_rtd_theme/static/css
+   done
+   for themefilefonts in usr/share/sphinx_rtd_theme/static/fonts/* ; do
+	mkdirp $webdocdir/html-theme/sphinx_rtd_theme/static/fonts
+	cp -rf $themefilefonts $webdocdir/html-theme/sphinx_rtd_theme/static/fonts
+   done
+unpack fonts-font-awesome
+   for fontfileawesome1 in usr/share/fonts-font-awesome/fonts/* ; do
+	mkdirp $webdocdir/html-theme/fonts-font-awesome/fonts
+	cp -rf $fontfileawesome1 $webdocdir/html-theme/fonts-font-awesome/fonts
+   done
+   for fontfileaw

Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks

[Holger Wansing]

Hi,

Dmitry Shachnev  wrote (Fri, 22 Mar 2024 18:46:25 +0300):
> On Fri, Mar 22, 2024 at 03:30:55PM +0100, Holger Wansing wrote:
> > Ok, I see.
> > So, we will need to get sphinx-rtd-theme-common installed on all debian.org
> > website mirrors, and it will just work (?) ...
> 
> From your earlier message it seemed to me like you are using the build
> tree in your deploy process, not the built package.
> 
> That is why I suggested not running dh_sphinxdoc, however my suggestion
> applied only to your deploy procedure. The package which is being uploaded
> to Debian archive should still use dh_sphinxdoc.
> 
> If you are using the built package and installing it on the remote server,
> then yes, install sphinx-rtd-theme-common and you should be good.

While working on adapting the parts/7doc script (from Debian Webmaster
Team's 'cron' repo), I realized that this is not going to work out of the
box: while the concept of the symlinks mentioned above is working fine,
when the debian-policy document is installed on a machine as usual
(means it recides in the same path as in the binary deb package, aka
/usr/share/doc/debian-policy/policy.html), we have the docs for the website
on the debian.org website machine in another path. That is in
/srv/www.debian.org/www/doc/debian-policy/.

That means the (relative) symlinks will not resolve!
Therefore I think the best solution here is, to change the relative
symlinks into absolute ones, on the debian.org website machine.

I have worked out the needed changes for cron/parts/7doc to deal with all
this (it works fine here locally). The debian-policy package could stay
unchanged.
I attach the patch here just for reference; will apply it, as soon as
sphinx-rtd-theme-common gets installed on wolkenstein
(working on a bugreport to DSA to get this done).

Closing #1066967 against sphinx-common/dh_sphinxdoc now.
Thanks python people for your help!

> Actually, I would move ${sphinxdoc:Depends} from Recommends to Depends,
> because the documentation is mostly unusable without the static files.

Ok. I will leave this mostly to Debian Policy maintainers.



Greetings
Holger

-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/parts/7doc b/parts/7doc
index b079aea..5a358d7 100755
--- a/parts/7doc
+++ b/parts/7doc
@@ -260,22 +260,24 @@ if [ "$lang" = "en" ]; then
 			install -p -m 664 `readlink -f $page` $destdir/Common_Content/images/$(basename $page)
 		fi
 	done
 fi
 }
 
 #
 
 mvhtml_sphinx()
 {
-# Copy of mvhtml(), modified so it copies the _images and _static subfolders too
-# This is needed by debian-policy since they moved to reStructuredText and Sphinx
+# Copy of mvhtml(), modified so it copies the _images, _sources, _static, _static/css
+# and _static/fonts subfolders too.
+# This is needed by some manuals which moved to reStructuredText and Sphinx
+# (like debian-policy and developers-reference) and use an html theme from read-the-docs.
 # This is probably uncomplete, since the _static folder contains symlinks to
 # some javascript that probably will not work.
 
 namedest=$1# destdir directory:  maint-guide
 basedir=$2 # binary package data dir.: usr/share/doc/maint-guide-fr/html
 addlang=${3:-NO} # $lang in filename: NO | ADD | YES
  # NO:  without $lang and leave it so
  # ADD: without $lang and add it (make link for en) (internal URL conversion)
  # YES: with$lang and leave it so (make link for en)
 lang=${4:-en}  # language name: en (default), fr, ...
@@ -317,20 +319,36 @@ for page in $pagepattern; do
 done
 
 if [ "$lang" = "en" ]; then
 	pagepattern="$basedir/_static/*"
 	for page in $pagepattern; do
 		if [ -f "`readlink -f $page`" ]; then
 			mkdirp $destdir/_static
 			install -p -m 664 `readlink -f $page` $destdir/_static/$(basename $page)
 		fi
 	done
+	pagepattern="$basedir/_static/css/*"
+	for page in $pagepattern; do
+		if [ -d "$basedir/_static/css" ]; then
+	# Replace all existing relative symlinks in css by absolute symlinks to the correct place.
+			mkdirp $destdir/_static/css
+			ln -sf /usr/share/sphinx_rtd_theme/static/css/$(basename $page) $destdir/_static/css/$(basename $page)
+		fi
+	done
+	pagepattern="$basedir/_static/fonts/*"
+	for page in $pagepattern; do
+		if [ -d "$basedir/_static/fonts" ]; then
+	# Replace all existing relative symlinks in fonts by absolute symlinks to the correct place.
+			mkdirp $destdir/_static/fonts
+			ln -sf /usr/share/sphinx_rtd_theme/static/fonts/$(basename $page) $destdir/_static/fonts/$(basename $page)
+		fi
+	done
 	pagepattern="$basedir/_images/*"
 	for page in $pagepattern ; do
 		if [ -f "`readlink -f $page`" ]; then
 			mkdirp $destdir/_images
 			install -p -m 664 `readlink -f $page` $destdir/_images/$(basename $page)
 		fi
 	done
 pagepattern="$basedir/_sources/*"
 for page in $pagepattern ; do
 if [ -f "`readlink -f $page`" ]; then

Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks

[Holger Wansing]

Hi,

Dmitry Shachnev  wrote (Fri, 22 Mar 2024 16:04:14 +0300):
> On Fri, Mar 22, 2024 at 01:46:48PM +0100, Holger Wansing wrote:
> > [...]
> > Anyway, the symlink points to some path inside the package build path, here:
> > /srv/debian-policy/debian-policy-4.6.2.1/debian/debian-policy/usr/share/sphinx_rtd_theme_static/css/theme.css
> > 
> > and that path does not exist.
> > Same in the debian-policy binary package.
> 
> This is expected. The path in the build tree is relative in a way that when
> a package is built and installed, it becomes working.

Ok, I see.
So, we will need to get sphinx-rtd-theme-common installed on all debian.org
website mirrors, and it will just work (?) ...

> The symlink is generated relative per Policy 10.5. And I think that even if
> dh_sphinxdoc generated it as absolute, dh_link would later change it to
> relative.
> 
> If you are trying to rely on something that is in the build directory, you
> have to turn relative symlinks into absolute ones on your own. Or just don't
> call dh_sphinxdoc, then you will get normal files.

... or we switch away from dh_sphinxdoc.
But there was already a hint, why this is a bad idea.
Will need to be evaluated...



Thanks for your time, guys!

Holger


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks

[Holger Wansing]

Hi,

Andrey Rakhmatullin  wrote (Fri, 22 Mar 2024 15:50:26 +0500):
> On Fri, Mar 22, 2024 at 11:29:11AM +0100, Holger Wansing wrote:
> > > I cannot reproduce this. I downloaded debian-policy source package and 
> > > built
> > > it in an up-to-date sid chroot. And the built package has this:
> > > 
> > >   $ dpkg-deb -c debian-policy_4.6.2.1_all.deb | grep theme.css
> > >   lrwxrwxrwx root/root 0 2024-02-24 15:39 
> > > ./usr/share/doc/debian-policy/policy.html/_static/css/theme.css -> 
> > > ../../../../../sphinx_rtd_theme/static/css/theme.css
> > 
> > But above output shows a filesize of 0B.
> > Shouldn't that be something different?
> Not for symlinks.

Ok.


> > Has ./usr/share/doc/debian-policy/policy.html/_static/css/theme.css any
> > useful content, when you open it?
> It's a symlink, it can't have content.
> It's target does have content, as shown in the quote below:
> 
> > > So, it is a symlink, not an empty file. When resolving the relative path,
> > > I get /usr/share/sphinx_rtd_theme/static/css/theme.css, and that file
> > > exists in sphinx-rtd-theme-common and is non-empty.
> 
> > if you open that theme.css file in the debian/debian-policy build path,
> > does it have any content?
> :-/
> 
> > Maybe it was bad wording, when I wrote 
> > "replaces files provided by read-the-doc theme by empty symlinks" in the 
> > subject of this bug.
> > Probably "symlinks pointing to a not-existing file" is more correct?
> To which non-existent files? Are they non-existent only when you don't
> have sphinx-rtd-theme-common installed?

Sure.

> > I don't know where's the problem in detail, I only see that in the
> > debian-policy binary package that file is empty, and therefore the html
> > layout is broken.
> It's not empty, it's a symlink that points to a non-existent (on your
> system) file.
> 
> > BTW: the same counts for all the symlinks under _static/fonts/:
> > 
> > holgerw@t520:~/debian-policy$ ls -la 
> > policy/debian/debian-policy/usr/share/doc/debian-policy/policy.html/_static/fonts/
> > total 64
> > drwxr-xr-x 2 holgerw holgerw 4096 Mar 22 11:17 .
> > drwxr-xr-x 5 holgerw holgerw 4096 Mar 22 11:17 ..
> > lrwxrwxrwx 1 holgerw holgerw   68 Mar 22 11:17 fontawesome-webfont.eot -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.eot
> > lrwxrwxrwx 1 holgerw holgerw   68 Mar 22 11:17 fontawesome-webfont.svg -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.svg
> > lrwxrwxrwx 1 holgerw holgerw   68 Mar 22 11:17 fontawesome-webfont.ttf -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.ttf
> > lrwxrwxrwx 1 holgerw holgerw   69 Mar 22 11:17 fontawesome-webfont.woff -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.woff
> > lrwxrwxrwx 1 holgerw holgerw   70 Mar 22 11:17 fontawesome-webfont.woff2 -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.woff2
> > lrwxrwxrwx 1 holgerw holgerw   64 Mar 22 11:17 Lato-BoldItalic.ttf -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-BoldItalic.ttf
> > lrwxrwxrwx 1 holgerw holgerw   66 Mar 22 11:17 Lato-BoldItalic.woff2 -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-BoldItalic.woff2
> > lrwxrwxrwx 1 holgerw holgerw   58 Mar 22 11:17 Lato-Bold.ttf -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-Bold.ttf
> > lrwxrwxrwx 1 holgerw holgerw   60 Mar 22 11:17 Lato-Bold.woff2 -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-Bold.woff2
> > lrwxrwxrwx 1 holgerw holgerw   60 Mar 22 11:17 Lato-Italic.ttf -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-Italic.ttf
> > lrwxrwxrwx 1 holgerw holgerw   62 Mar 22 11:17 Lato-Italic.woff2 -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-Italic.woff2
> > lrwxrwxrwx 1 holgerw holgerw   61 Mar 22 11:17 Lato-Regular.ttf -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-Regular.ttf
> > lrwxrwxrwx 1 holgerw holgerw   63 Mar 22 11:17 Lato-Regular.woff2 -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/Lato-Regular.woff2
> > lrwxrwxrwx 1 holgerw holgerw   66 Mar 22 11:17 RobotoSlab-Bold.woff2 -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/RobotoSlab-Bold.woff2
> > lrwxrwxrwx 1 holgerw holgerw   69 Mar 22 11:17 RobotoSlab-Regular.woff2 -> 
> > ../../../../../sphinx_rtd_theme/static/fonts/RobotoSlab-Regular.woff2
> > 
> > All those symlinks are pointing to a not-existing target here.
> Only because you don't have sphinx-rtd-theme-common ins

Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks

[Holger Wansing]

Hi Dmitry,

Dmitry Shachnev  wrote (Fri, 22 Mar 2024 00:35:57 +0300):
> I cannot reproduce this. I downloaded debian-policy source package and built
> it in an up-to-date sid chroot. And the built package has this:
> 
>   $ dpkg-deb -c debian-policy_4.6.2.1_all.deb | grep theme.css
>   lrwxrwxrwx root/root 0 2024-02-24 15:39 
> ./usr/share/doc/debian-policy/policy.html/_static/css/theme.css -> 
> ../../../../../sphinx_rtd_theme/static/css/theme.css

But above output shows a filesize of 0B.
Shouldn't that be something different?
Has ./usr/share/doc/debian-policy/policy.html/_static/css/theme.css any
useful content, when you open it?

> So, it is a symlink, not an empty file. When resolving the relative path,
> I get /usr/share/sphinx_rtd_theme/static/css/theme.css, and that file
> exists in sphinx-rtd-theme-common and is non-empty.

As above:
if you open that theme.css file in the debian/debian-policy build path,
does it have any content?

If I open it here, nano shows "New file" in the status bar at the bottom,
so the file does not exist.

Maybe it was bad wording, when I wrote 
"replaces files provided by read-the-doc theme by empty symlinks" in the 
subject of this bug.
Probably "symlinks pointing to a not-existing file" is more correct?

> The only issue I see is that sphinx-rtd-theme-common is in Recommends of
> debian-policy, not in Depends. But that is because ${sphinxdoc:Depends}
> was put there.
> 
> Am I doing something wrong?

I don't know where's the problem in detail, I only see that in the
debian-policy binary package that file is empty, and therefore the html
layout is broken.

BTW: the same counts for all the symlinks under _static/fonts/:

holgerw@t520:~/debian-policy$ ls -la 
policy/debian/debian-policy/usr/share/doc/debian-policy/policy.html/_static/fonts/
total 64
drwxr-xr-x 2 holgerw holgerw 4096 Mar 22 11:17 .
drwxr-xr-x 5 holgerw holgerw 4096 Mar 22 11:17 ..
lrwxrwxrwx 1 holgerw holgerw   68 Mar 22 11:17 fontawesome-webfont.eot -> 
../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.eot
lrwxrwxrwx 1 holgerw holgerw   68 Mar 22 11:17 fontawesome-webfont.svg -> 
../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.svg
lrwxrwxrwx 1 holgerw holgerw   68 Mar 22 11:17 fontawesome-webfont.ttf -> 
../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.ttf
lrwxrwxrwx 1 holgerw holgerw   69 Mar 22 11:17 fontawesome-webfont.woff -> 
../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.woff
lrwxrwxrwx 1 holgerw holgerw   70 Mar 22 11:17 fontawesome-webfont.woff2 -> 
../../../../../sphinx_rtd_theme/static/fonts/fontawesome-webfont.woff2
lrwxrwxrwx 1 holgerw holgerw   64 Mar 22 11:17 Lato-BoldItalic.ttf -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-BoldItalic.ttf
lrwxrwxrwx 1 holgerw holgerw   66 Mar 22 11:17 Lato-BoldItalic.woff2 -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-BoldItalic.woff2
lrwxrwxrwx 1 holgerw holgerw   58 Mar 22 11:17 Lato-Bold.ttf -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-Bold.ttf
lrwxrwxrwx 1 holgerw holgerw   60 Mar 22 11:17 Lato-Bold.woff2 -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-Bold.woff2
lrwxrwxrwx 1 holgerw holgerw   60 Mar 22 11:17 Lato-Italic.ttf -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-Italic.ttf
lrwxrwxrwx 1 holgerw holgerw   62 Mar 22 11:17 Lato-Italic.woff2 -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-Italic.woff2
lrwxrwxrwx 1 holgerw holgerw   61 Mar 22 11:17 Lato-Regular.ttf -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-Regular.ttf
lrwxrwxrwx 1 holgerw holgerw   63 Mar 22 11:17 Lato-Regular.woff2 -> 
../../../../../sphinx_rtd_theme/static/fonts/Lato-Regular.woff2
lrwxrwxrwx 1 holgerw holgerw   66 Mar 22 11:17 RobotoSlab-Bold.woff2 -> 
../../../../../sphinx_rtd_theme/static/fonts/RobotoSlab-Bold.woff2
lrwxrwxrwx 1 holgerw holgerw   69 Mar 22 11:17 RobotoSlab-Regular.woff2 -> 
../../../../../sphinx_rtd_theme/static/fonts/RobotoSlab-Regular.woff2

All those symlinks are pointing to a not-existing target here.



Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1064593: debian-policy: missing static resources for www.debian.org policy page

[Holger Wansing]

Hi,

James Addison  wrote (Fri, 15 Mar 2024 10:42:39 +):
> I'm not much of a perlmonger but this might be a problem somewhere in:
> 
>   
> https://sources.debian.org/src/sphinx/7.2.6-5/debian/dh-sphinxdoc/dh_sphinxdoc/?hl=409#L389-L413
> 
> When I modify that code to always follow the 'absolute link' path, I still
> get relative links to the theme.css file in the debian/ package build dirs.
> 
> (note: this function also exists in imagemagick-6-doc, so any problem/fix
> should not forget about that package too)

I filed 
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1066967
for this.


Holger


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1064593: debian-policy: missing static resources for www.debian.org policy page

[Holger Wansing]

Hi guys,

Stéphane Blondon  wrote (Mon, 4 Mar 2024 08:29:10 
+0100):
> Hello,
> 
> Le dim. 3 mars 2024 à 11:49, Holger Wansing  a écrit :
> > So, no problem with latest Sphinx version, it seems the integration in the
> > debian-policy package is the problem (aka debian/rules) ...
> 
> Thank you for the search.
> 
> I have two wild guesses based on broken symlink assumption:
> 
> 1. By dh_auto_install
> 
> buildd create symbolic links to the files (like theme.css) provided by
> python3-sphinx-rtd-theme:
> lrwxrwxrwx root/root 0 2024-02-24 12:39
> ./usr/share/doc/debian-policy/policy.html/_static/css/theme.css ->
> ../../../../../sphinx_rtd_theme/static/css/theme.css
> (found in the log file)
> 
> Then the target dh_auto_install in debian/rules from debian_policy
> moves files (line 15):
> mv debian/tmp/* debian/debian-policy/
> 
> The symlink is relative so it could be broken.

It appears to me that the target for that symlink 
(../../../../../sphinx_rtd_theme/static/css/theme.css) is not existing
and therefore we get an empty file.

I did some testing with debuild, and changed debian/rules (line 4) like

-   dh $@ --with sphinxdoc
+   dh $@

and that way I get a valid html document with the new theme working !!!

(That is something of a revert of
https://salsa.debian.org/dbnpolicy/policy/-/commit/528ad4d79a76690eeb0504fd6c094a88ddb9739d
 )

Please note that I did not check for any other differences in the package
created that way compared to the latest version in the archive (debdiff).
An sbuild run was successful that way as well.

Seems there is something wrong in the debhelper / dh_sphinxdoc world 
(or at least an incompatibility with read-the-doc themes) ...

But that's out of my skills

Applying above change could at least be a temporary way to get the policy
back in shape on the website ...


Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1064593: debian-policy: missing static resources for www.debian.org policy page

[Holger Wansing]

Hi,

Stéphane Blondon  wrote (Tue, 27 Feb 2024 21:27:50 
+0100):
> Hello,
> 
> Le dim. 25 févr. 2024 à 14:24, Holger Wansing  a écrit :
> >
> > Hi,
> > Seems there is more than only one issue:
> >
> > 1.
> > In the binary package (debian-policy latest version) the above files and
> > directories are existing, but the files are all empty (0 B size).
> > However, in the previous version (4.6.2.0) the javascript .js files
> > are also empty (0 B), so that's most probably not the issue.
> > [...]
> > In a local build here, they are all fine, and the document is displayed
> > correctly. But that's build on bookworm, so sphinx version 5.3.0.
> > The binary packages built by buildd will get build on sphinx 7.2.x
> > I think, so maybe there is the difference?
> > Maybe we need some adaption for latest sphinx version?
> 
> 
> Sphinx Changelog (https://www.sphinx-doc.org/en/master/changes.html)
> shows several incompatibilities between 5.3 and 7 branches.
> Can we get the logs of the built of the package?
> 
> I will try to do some tests with Sphinx 7.2 in a virtualenv too.

I tested building it on a trixie system:
a build with just a 'make' in 'policy' dir is successful, the generated
html files are valid, with the new Debian theme.

So, no problem with latest Sphinx version, it seems the integration in the 
debian-policy package is the problem (aka debian/rules) ...


Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1064593: debian-policy: missing static resources for www.debian.org policy page

[Holger Wansing]

Hi,

James Addison  wrote (Sun, 25 Feb 2024 11:05:06 +):
> On Sun, 25 Feb 2024 at 08:07, Sean Whitton  wrote:
> > ...
> > On Sun 25 Feb 2024 at 08:44am +01, Holger Wansing wrote:
> > > ...
> > > Am 24. Februar 2024 20:15:41 MEZ schrieb James Addison 
> > > :
> > >>
> > >>(this may relate closely to #915583)
> > >>
> > >>Some of the web resources referenced by the online[1] copy of the Debian 
> > >>policy
> > >>manual seem to return HTTP 404 responses at the moment, meaning that the
> > >>intended Sphinx CSS theming fails to apply.
> > >>
> > >>[1] - https://www.debian.org/doc/debian-policy/
> > >
> > > Hmm, locally built it's fine here ...
> > > ...
> > The new debian.css is there.  So, which file is it that's missing?
> 
> Thanks for checking - yep, the debian.css file does appear to be fine.
> The following paths (relative to the policy base) produce HTTP 404
> responses:
> 
>   * _static/css/theme.css
>   * _static/jquery.js
>   * _static/sphinx_highlight.js
>   * _static/js/theme.js

Seems there is more than only one issue:

1.
In the binary package (debian-policy latest version) the above files and 
directories are existing, but the files are all empty (0 B size).
However, in the previous version (4.6.2.0) the javascript .js files
are also empty (0 B), so that's most probably not the issue.
I remember we don't have full javascript functionality in our sphinx-based
manuals on debian.org for a longer time, search is not working for example. 
That's #1026446, #872944, #987943.

In a local build here, they are all fine, and the document is displayed
correctly. But that's build on bookworm, so sphinx version 5.3.0.
The binary packages built by buildd will get build on sphinx 7.2.x
I think, so maybe there is the difference?
Maybe we need some adaption for latest sphinx version?
   

2. 
The first file from above list _static/css/theme.css is likely to be
the point, since the html layout is completely broken.
That file is also empty in latest debian-policy binary package.
Since it is fine in local build here, also an issue with latest sphinx
version maybe ???
Or do we no longer need _static/css/theme.css, as we now have 
_static/debian.css ?


3.
Despite the fact, that the files from above are empty, there seems to be
another issue with debian.org website:
the subdirectories under _static are not existing on debian.org, as well as 
the files within of course (like _static/css/theme.css).
Apparently there is some more magic needed in webmaster-team's cron
https://salsa.debian.org/webmaster-team/cron/-/blob/master/parts/7doc?ref_type=heads#L319
to get such files copied over to debian.org during website build.

But first, we need to have a working version in the binary package,
since that's the basis for website build.


Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1064593: debian-policy: missing static resources for www.debian.org policy page

[Holger Wansing]

Hi,

Am 24. Februar 2024 20:15:41 MEZ schrieb James Addison :
>
>(this may relate closely to #915583)
>
>Some of the web resources referenced by the online[1] copy of the Debian policy
>manual seem to return HTTP 404 responses at the moment, meaning that the
>intended Sphinx CSS theming fails to apply.
>
>[1] - https://www.debian.org/doc/debian-policy/

Hmm, locally built it's fine here ...

@Stéphane: could you take a look?


Holger





-- 
Sent from /e/ OS on Fairphone3

Bug#915583: about html_static_path

[Holger Wansing]

Hi Sean,

Sean Whitton  wrote (Sat, 24 Feb 2024 11:58:59 +0800):
> Attached is the patch I prepared, which I couldn't get to work.  Maybe
> you can see what is wrong.  Thanks!

As I know it, the debian.css file has to reside in policy/_static.
And activate (un-comment) the path declaration for that in line 105 of 
conf.py.in.

Additionally, as I already wrote somewhere, for navigating it would be good
to have the Next/Previous buttons at the top of the page as well, not only
at the bottom.

And: do we want to have the 
"Built with Sphinx using a theme provided by Read the Docs."
in the footer? If not, that could be suppressed by
html_show_sphinx = False
in conf.py.in.


My diff for conf.py.in would be like this (with above suggestions):

diff --git a/policy/conf.py.in b/policy/conf.py.in
index d516d7b..4ea4df6 100755
--- a/policy/conf.py.in
+++ b/policy/conf.py.in
@@ -84,13 +84,19 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'nature'
+html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+   # To get previous/next buttons at the top and the bottom:
+   'prev_next_buttons_location': 'both'
+}
+
+# Overwrite theme to fit Debian colors
+html_css_files = ['debian.css']
 
 # Override the title to remove the unnecessary "documentation" suffix.
 html_title = "Debian Policy Manual v@VERSION@"
@@ -98,11 +104,14 @@ html_title = "Debian Policy Manual v@VERSION@"
 # Suppress the copyright notice.
 html_show_copyright = False
 
+# Hide “Created using Sphinx” in the HTML footer
+html_show_sphinx = False
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 #
-# html_static_path = ['_static']
+html_static_path = ['_static']
 
 
 # -- Options for HTMLHelp output ----------



Best regards
Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#915583: about html_static_path

[Holger Wansing]

Sean Whitton  wrote:
> On Fri 29 Dec 2023 at 07:08am +01, Stéphane Blondon wrote:
> 
> > Yes, html_static_path must be set but it's already the case in conf.py.in:
> > https://sources.debian.org/src/debian-policy/4.6.2.0/policy/conf.py.in/#L105
> >
> > I guess conf.py is generated from conf.py.in so we only need to keep
> > the current setup.
> 
> That line is commented out, though.  Are you saying it takes on its
> default value in that case?

I think it would be good to un-comment such lines which are needed, so it's 
clear without doubt, what is used and active.
Works fine here BTW.


Holger

-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#915583: Bug#1059730: debian-policy: switch to new Debian-conform html theme for Sphinx/reST

[Holger Wansing]

[ Hrrr, I sent this to the wrong bug #1059730; so resending to the correct 
one #915583 for completeness ]


Holger Wansing  wrote (Sun, 31 Dec 2023 10:02:29 +0100):
> Hi Sean and Stéphane,
> 
> Am 30. Dezember 2023 23:43:17 MEZ schrieb Sean Whitton 
> :
> >Possibly some of your changes could be applied on top of that?
[...]
> @Stéphane: 
> The URL is 404 now, could you provide the draft again somewhere?
> (<http://stephane.yaal.fr/tmp/policy/>)

Thanks, your files are back online.
They look really good indeed. 
Especially how the menu/sidebar is shown/not shown on small screens 
(smartphones) is fine, that was an open point in my proposal :-)

BTW: I think it would be good to have the 'Next'/'Previous' buttons
at the top additionally to those at the bottom.
The theme supports this via a config option. Simply set

html_theme_options = {
# To get previous/next buttons at the top and the bottom:
'prev_next_buttons_location': 'both'
}

in conf.py.in.


Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1059730: debian-policy: switch to new Debian-conform html theme for Sphinx/reST

[Holger Wansing]

Hi,

Holger Wansing  wrote (Sun, 31 Dec 2023 10:02:29 +0100):
> Hi Sean and Stéphane,
> 
> Am 30. Dezember 2023 23:43:17 MEZ schrieb Sean Whitton 
> :
> >Possibly some of your changes could be applied on top of that?
[...]
> @Stéphane: 
> The URL is 404 now, could you provide the draft again somewhere?
> (<http://stephane.yaal.fr/tmp/policy/>)

Thanks, your files are back online.
They look really good indeed. 
Especially how the menu/sidebar is shown/not shown on small screens 
(smartphones) is fine, that was an open point in my proposal :-)

BTW: I think it would be good to have the 'Next'/'Previous' buttons
at the top additionally to those at the bottom.
The theme supports this via a config option. Simply set

html_theme_options = {
# To get previous/next buttons at the top and the bottom:
'prev_next_buttons_location': 'both'
}

in conf.py.in.


Holger



-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#1059730: debian-policy: switch to new Debian-conform html theme for Sphinx/reST

[Holger Wansing]

Hi Sean and Stéphane,

Am 30. Dezember 2023 23:43:17 MEZ schrieb Sean Whitton 
:
>Hello,
>
>On Sat 30 Dec 2023 at 11:11pm +01, Holger Wansing wrote:
>
>> Source: debian-policy
>> Tags: patch
>>
>> Debian Policy has been migrated to restructedText / Sphinx.
>> However, the current html theme is not conform with the look of the Debian 
>> website.
>>
>> Bug #1053549 (https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549)
>> requests to create a new theme for Sphinx-based documents "to match our docs
>> appearance with the Debian website colours etc."
>>
>> I have worked on this and a patch is attached, to fulfill this goal.
>>
>> An preview how the Debian Policy would look like with this theme can be 
>> found at
>> https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/debian-policy-manual/
>>
>> Please consider to apply this proposal.
>
>We're actually in the middle of applying someone else's proposal, here: 
>#915583.
>
>Possibly some of your changes could be applied on top of that?

Yes, of course.
I wasn't aware of other work on this front.
And Stéphane is for sure the right guy for CSS/theme topics, he has much
experience there, other than me. 
I just wanted to push things forward somehow.

So, let's see how it goes and if things remain from this proposal


@Stéphane: 
The URL is 404 now, could you provide the draft again somewhere?
(<http://stephane.yaal.fr/tmp/policy/>)

BTW: I missed the MR you filed for my release-notes's draft regarding CSS, 
sorry. 
I will follow up there shortly.


Greetings
Holger

-- 
Sent from /e/ OS on Fairphone3

Bug#1059730: debian-policy: switch to new Debian-conform html theme for Sphinx/reST

[Holger Wansing]

Source: debian-policy
Tags: patch

Debian Policy has been migrated to restructedText / Sphinx.
However, the current html theme is not conform with the look of the Debian 
website.

Bug #1053549 (https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1053549)
requests to create a new theme for Sphinx-based documents "to match our docs 
appearance with the Debian website colours etc."

I have worked on this and a patch is attached, to fulfill this goal.

An preview how the Debian Policy would look like with this theme can be found at
https://people.debian.org/~holgerw/sphinx-theme-for-debian/alabaster/debian-policy-manual/

Please consider to apply this proposal.


BTW:
I have also requested to switch the developers-reference to the same
theme (https://salsa.debian.org/debian/developers-reference/-/merge_requests/47)
and the new release-notes for trixie are already using it
(https://www.debian.org/releases/testing/release-notes/index.en.html).


So long
Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
>From 1193ec1df212565fc5344a9a4bf31b65275cfc5b Mon Sep 17 00:00:00 2001
From: Holger Wansing 
Date: Sat, 30 Dec 2023 22:49:20 +0100
Subject: [PATCH] Switch to new theme for sphinx-based documentation

---
 policy/_static/openlogo-policy-manual.png | Bin 0 -> 15237 bytes
 policy/_static/openlogo-policy-manual.xcf | Bin 0 -> 7904 bytes
 policy/conf.py.in |  13 ++---
 3 files changed, 10 insertions(+), 3 deletions(-)
 create mode 100644 policy/_static/openlogo-policy-manual.png
 create mode 100644 policy/_static/openlogo-policy-manual.xcf

diff --git a/policy/_static/openlogo-policy-manual.png b/policy/_static/openlogo-policy-manual.png
new file mode 100644
index ..bd449f163feefe9e3c0b0f473acfe11591e275f5
GIT binary patch
literal 15237
zcmeHtWmKF?)^6kO8nhdCZ`|FT5L_E*oThOIPJrML0t9!L1PBCo3+@sm5G+U_K#+u7
zl5=L}%>Cwm-<`GY{WrZ}T(KYVWFk>59?TRKmfezytsQI4a8Wx(|PCAKs03ERJjMfGGEU1
zZPJbh-^YDh4fOBY$V=%of72y-s(9lM`l7$X`}F>8kc8XDTAPwrzQ7N#zpC`1N#h@eD5N`>;Y{FYZZMZPv}!Eo?l2
zH%vNpeGjgbce6hsk`taT-1E6^A1%69BtzpS?~;4pK5f0bA)@%SY^hUGR{EZp`R8o;
zTAk6s_N39xS)D}+;n<$v5K%CW-Obtc&>rVck?WJl>oT#S%k7C^zfPCcF3r8W(~h>*
zfJu9AdJ`_A#1RC%n)b~VaO
z?9^k~I+`_G+Yj3+@;cY4A?ivk0l)NRf`RM@be4BTpX!E>(kC3A6$*L2UmUV
zdARJ@P|7TR#^iN%Om(pN@oz|a6mpOoY7_8bLo~bm$S@l2%#?0WuJ861rAD0?!fzs5
zd3(0@_6Ye`4P7b{KB~cY;xmV|>Wn^EkOAe_#Q4cYftlRIT_j(@5sr#flsAt|%Of*-
z8Bo$am*V(}$+1SDGT(Oj=hp+|aP!J~I0%z%VqVN$2oD<|E|uqHQGf+t?^*XuVdI?N
z#8o*ec63!a5xaD3G{B3xPA*N0)7EO7Z)ZZ37yT(EF3^Q{
z%&;2Fw9ADoEZgPT=t#2Hw2xL+wazatSqMKsqOfhli1zyUY`AU=NnS<(u=`cdZ)m~g;TYRO$K&*TMh>LZG%Vo`QfnL
zS0%*Rx@FlnxbH(<;`rD_R?~R-G7=$l1ZjF(*e95uO~$ksc(86x{jgzs
z@~!;`$jM}?JrK?<=O~9Vue6dV6hC#1r+Isjyfx0}IzoRW_-$PXK^0%KBIt6HZQ5*g
zXz=*B|Tc
zxGnq%XwO$a^0mJIJS)PL`g!?LT46H!UBT_@_(7bP-XpQPM?X3}uP6qqbI94eBb?54
zp>MPo)2SCZ@n=BFZKYz?W@)P^F0ICyp_49BBith=PP+nfW^?`yti;6XxkNJ!=ylWn
zyo)VEEzeaJ5C`K0GOx2)O_a8HRSXlVlA*Y49)#Bu
z$fRWN%aREkzr7b9guSfhtSln(GWHH^LOH5_20H#$H{_a%KWG$>U#Gj-{%9d2Bz0A$
zBwd4$ZqDvz(0sLqebT)Gdvg<+y^VWu%e8m?FpsaJ3xB;K>QJ18oj$a98UUo`Py
z3;rKU%{e%a!(Sg#1b$itNSjt#Sb%5n(I|L8(M~Q
z0fbHSk-8O)!v2|S`Syb`#F_m*E$QWXIaxL8n2uwYOTr;GoE=40DqeEM*%+j#>}bAH
zaW}g?Inclp1JILG!Xz@|C>-e@@Pi{`xnm?90Y0$d4_0;Yy%>0Xw`yEk`v1#5{
zW3+IL%iwVmbr7^2ZSm(5@-k8UT^Ql7XfRC^ZLDc`nHu7BW-%b6kfvm-l4tan4%xd4aMe5|tvt
zd!#`MUsXz;HW@7Jd4W-PS}E3&8Ha2^R%Hij?-1t(HFY%C9OZp8R<~N@XKQmHV)qIz
z;kILqv?u`?+x`H|mgd%Y)e*}2X0LfPeT3Hp)u^Hk$aR7h?IGV3{K-)iC9T?HypyWM
zzffdJisA>>=n3s$@C=C>a_7_bWioNd^`-GgtJOT)0)17Ms5>8wor^)sZfBUJj;@7&
zj&#

Bug#1053305: Fw: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ examples suffer escape damage

[Holger Wansing]

Control: tags -1 + patch


наб  wrote:
>  You should have received a copy of the GNU General Public License
>  along with this package; if not, see https://www.gnu.org/licenses/;.
> -- >8 --
> and I almost just copied this into d/copyright verbatim.
> 
> Oddly, all other <> pairs, even in those same  hunks,
> are correctly (un)escaped? So unclear to me how this happened.

Using   entites does not work here.
Should be replaced by < >.

Patch (tested) attached.


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/copyright-format-1.0.xml b/copyright-format-1.0.xml
index 954a65b..0920a84 100644
--- a/copyright-format-1.0.xml
+++ b/copyright-format-1.0.xml
@@ -1283,7 +1283,7 @@ License: GPL-2+
  GNU General Public License for more details.
  .
  You should have received a copy of the GNU General Public License
- along with this package; if not, see https://www.gnu.org/licenses/;.
+ along with this package; if not, see <https://www.gnu.org/licenses/>.
 Comment:
  On Debian systems, the full text of the GNU General Public License
  version 2 can be found in the file '/usr/share/common-licenses/GPL-2'.
@@ -1363,7 +1363,7 @@ License: GPL-2+
  GNU General Public License for more details.
  .
  You should have received a copy of the GNU General Public License
- along with this package; if not, see https://www.gnu.org/licenses/;.
+ along with this package; if not, see <https://www.gnu.org/licenses/>.
 Comment:
  On Debian systems, the full text of the GNU General Public License
  version 2 can be found in the file '/usr/share/common-licenses/GPL-2'.]]>

Bug#1053305: Fw: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ examples suffer escape damage

[Holger Wansing]

Package: debian-policy
Severity: minor
X-Debbugs-CC: наб 


This has to be fixed in the package.
Turning this into a bugreport against debian-policy.




Date: Sun, 1 Oct 2023 01:42:47 +0200
From: наб 
To: debian-...@lists.debian.org
Subject: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ 
examples suffer escape damage


File appears untagged, as does everything up to /doc. So posting here.

https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/,
Example 3. Simple and Example 4. Complex say
-- >8 --
 You should have received a copy of the GNU General Public License
 along with this package; if not, see https://www.gnu.org/licenses/;.
-- >8 --
and I almost just copied this into d/copyright verbatim.

Oddly, all other <> pairs, even in those same  hunks,
are correctly (un)escaped? So unclear to me how this happened.

Best,
наб


-- 
Holger Wansing 
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076


signature.asc
Description: PGP signature

Bug#1042779: developers-reference: overhaul of chapter about i18n / l10n

[Holger Wansing]

Package: developers-reference
Severity: normal


Hi,

yesterday I was a bit shocked when reading chapter 8 of the developers-ref:
https://www.debian.org/doc/manuals/developers-reference/l10n.en.html

That chapter has several wrong/bad sentences (or is heavily outdated, if that
things have been correct like that at some time).

I comment here on the different parts; a complete patch which integrates all
this proposals is attached to this mail.



"For program messages, the gettext infrastructure is used most of the time. 
Most of the time, the translation is handled upstream within projects like the 
Free Translation Project, the GNOME Translation Project or the KDE Localization 
project.


... is used most of the time. Most of the time, the translation ...

Please avoid this doubled use of "most of the time" in direct repeating.
(only cosmetic, yes.)



The only centralized resources within Debian are the Central Debian 
translation statistics, where you can find some statistics about the 
translation 
files found in the actual packages, but no real infrastructure to ease the 
translation process."


... where you can find some statistics ... but no real infrastructure to ease 
the 
translation process.

This is not true. The statistics page provides the possibility to directly
download the po files by one click! This is for sure much easier than
loading the whole source package, uncompress it and pick the po file out from
there! So, it's much more than just a statistics page, and it makes translators
work much easier!
(What was meant here is probably, that Debian has no own pootle or Weblate
server, where the translation can be done directly online?)




For debconf templates, maintainers should use the po-debconf package to ease 
the work of translators, who could use the DDTP to do their work (but the 
French and Brazilian teams don't). Some statistics can be found both on the 
DDTP site (about what is actually translated), and on the Central Debian 
translation statistics site (about what is integrated in the packages).


Here we have some wrong facts. The DDTP infrastructure is only for translating
the package descriptions!
It does not handle debconf template translations!
And the DDTP site does not have statistics about debconf template translations.
(Don't know, if this was different in the past, but this is the status quo.)



For package-specific documentation (man pages, info documents, other formats),
almost everything remains to be done.


This is also not true!
We have many translated manpages now for example, so we cannot say 
"nothing has been done on this".




For all other material (gettext files, man pages, or other documentation), the 
best solution is to put your text somewhere on the Internet, and ask on 
debian-i18n for a translation in different languages. Some translation team 
members are subscribed to this list, and they will take care of the translation 
and of the reviewing process. Once they are done, you will get your translated 
document from them in your mailbox.


... the best solution is to put your text somewhere on the Internet ...

This seems rather weird for me. Debian is such a huge community with much
infrastructure, we should not recommend to "put the text somewhere on the 
Internet". That sounds poor.


... Once they are done, you will get your translated document from them in 
your mailbox. ...

There is a big consensus, that translations are sent via wishlist bugreports.



Please find a patch attached (can be seen as a proposal, of course).


So long
Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/source/l10n.rst b/source/l10n.rst
index c66173d..8935907 100644
--- a/source/l10n.rst
+++ b/source/l10n.rst
@@ -42,7 +42,7 @@ manual task, and the process depends on the kind of text you want to see
 translated.
 
 For program messages, the gettext infrastructure is used most of the
-time. Most of the time, the translation is handled upstream within
+time. Often the translation is handled upstream within
 projects like the `Free Translation
 Project <https://translationproject.org/html/welcome.html>`__, the
 `GNOME Translation
@@ -51,7 +51,7 @@ Localization <https://l10n.kde.org/>`__ project. The only centralized
 resources within Debian are the `Central Debian translation
 statistics <https://www.debian.org/intl/l10n/>`__, where you can find
 some statistics about the translation files found in the actual
-packages, but no real infrastructure to ease the translation process.
+packages and download those files.
 
 Package descriptions have translations since many years and Maintainers
 don't need to do anything special to support translated package
@@ -59,12 +59,9 @@ descriptions; translators should use the `Debian Description Translation
 Project (DDTP) <https://ddtp.debian.org/>`__.
 
 For ``debconf`` templates, maintainers should use the ``

Bug#817914: developers-reference: globally change "new maintainer" into "new member"

[Holger Wansing]

Hi,

Holger Levsen  wrote:
> > Therefore, it's of course not possible and also not useful, to substitute
> > all "maintainer" into "member" and the like (think about phrases like
> > "maintainer script" and "maintainer field in control" and ...), which are
> > still correct and will not be renamed into "member script" or "member 
> > field".
> > 
> > This only as a explanation, why not all occurrences of "maintainer" have
> > been switched to "member".
> 
> I totally agree and I also think you've done a few substituion too many,
> see below...
> 
> > (Yes, this relativizes the bug title a bit :-) )
> > I hope I got it mostly right.
> 
> in any case: many thanks for your quick response! let's get this settled
> now!
> 
> some (quick) comments, stuff I havent commented is fine IMO.
> 
> > -Given how easy it is to become a Debian Maintainer, you might want
> > +Given how easy it is to become a Debian Member, you might want
> >  to only sponsor people who plan to join. 
> 
> to become a Maintainer?

Maybe ...
But as a first step, it would be enough to only be a member.
For team maintained packages you can also do package work | package uploading
work as a member (at least these are my experiences; see below).

> > -The process of registering as a developer is a process of verifying your
> > +The process of registering as a member is a process of verifying your
> 
> ... a maintainer?

Here we refer to the NM process itself, which is officially named "New Member
process" these days.
So I think "member" is fine here.

> (maybe then we also need one paragraph explaining that developers are
> maintainers too? and developers are members, but members not necessarily
> developers nor maintainers? ;)

Yes, but question is, if we want to make it that complicated :-)
Remember it should be understandable for new people ...

> > -Therefore, we need to verify new maintainers before we can give them 
> > accounts
> > +Therefore, we need to verify new members before we can give them accounts
> >  on our servers and let them upload packages.
> 
> not sure if members can get server access. maintainers surely can. maybe
> "new developers/maintainers"? (also to answer my own question in the
> previous paragraph, maybe be explicit and say
> 'member/developer/maintainer' if we mean that?

Members have chance to get permission to access dillon :-)))
At least in my case.

I am not a developer, and I am not mentioned as a maintainer in some packages'
control file, so I assume I am a member? ;-))
And I got upload permissions for d-i packages, and I got access to dillon.
As it seems the rules are always somewhat flexible ...

> 
> > -Resources for Debian Developers and Debian Maintainers
> > +Resources for Debian Members\
> 
> see above :)

I assume that all developers and maintainers are also members (in german we
say "kleinster gemeinsamer Nenner").

As written above: maybe we should not make this more complicated as needed
and use 'member' as a cover term?

> Even if this seems a bit confusing now I'd hope it was that bad. Have
> you seen anything where you would like to rework your patch or do you
> think it should rather go in as such?
> 
> (once it goes in it will trigger translation updates so we better are
> careful...)

This is why I first thought "Huh it's maybe to late for this change now?", 
since translators maybe have only little chance to catch up...
But to not postpone this too much I prepared a patch anyway.



As a summary:
I see no strict need to do reworking on my patch IMHO.
(You can always find corner cases, where the terms are debatable, because
of historical growth of the document and the rules in Debian, as already
said. But I think it should fit this way.)


So long
Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#817914: developers-reference: globally change "new maintainer" into "new member"

[Holger Wansing]

Moin,

Holger Levsen  wrote:
> Hi Holger,
> 
> yes, a patch to fix this would be awesome! Many thanks in advance! :)

Patch is attached!

In fact, this member/maintainer/developer naming thing is somewhat tricky,
and sometimes it's also irritating IMO (at least for people being new to 
Debian).

However, this is because the documents have developed over time, so the
document has probably been written in times where only the developer role
was existing, and later the maintainer role and then the member role has
been introduced.

Therefore, it's of course not possible and also not useful, to substitute
all "maintainer" into "member" and the like (think about phrases like
"maintainer script" and "maintainer field in control" and ...), which are
still correct and will not be renamed into "member script" or "member field".

This only as a explanation, why not all occurrences of "maintainer" have
been switched to "member".
(Yes, this relativizes the bug title a bit :-) )
I hope I got it mostly right.


Regards
Holger




-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/beyond-pkging.dbk b/beyond-pkging.dbk
index 5051bef..bead81e 100644
--- a/beyond-pkging.dbk
+++ b/beyond-pkging.dbk
@@ -386,7 +386,7 @@ to learn them?
 
 It's also a good idea to know where they stand with respect to Debian: do
 they agree with Debian's philosophy and do they intend to join Debian?
-Given how easy it is to become a Debian Maintainer, you might want
+Given how easy it is to become a Debian Member, you might want
 to only sponsor people who plan to join. That way you know from the start
 that you won't have to act as a sponsor indefinitely.
 
diff --git a/new-maintainer.dbk b/new-maintainer.dbk
index 50392a1..6228dc5 100644
--- a/new-maintainer.dbk
+++ b/new-maintainer.dbk
@@ -4,7 +4,7 @@
%commondata;
 ]>
 
-Applying to Become a Maintainer
+Applying to Become a Member
 
 Getting started
 
@@ -75,7 +75,7 @@ that list and an experienced developer will volunteer to help.
 
 
 In addition, if you have some packages ready for inclusion in Debian, but are
-waiting for your new maintainer application to go through, you might be able
+waiting for your new member application to go through, you might be able
 find a sponsor to upload your package for you.  Sponsors are people who are
 official Debian Developers, and who are willing to criticize and upload your
 packages for you. Please read the debian-mentors FAQ at 
 
 
-Registering as a Debian developer
+Registering as a Debian member
 
 Before you decide to register with , you will
 need to read all the information available at the New Members Corner.  It
 describes in detail the preparations you have to do before you can register to
-become a Debian developer.  For example, before you apply, you have to read the
+become a Debian member.  For example, before you apply, you have to read the
 Debian Social
-Contract.  Registering as a developer means that you agree with and
+Contract.  Registering as a member means that you agree with and
 pledge to uphold the Debian Social Contract; it is very important that
-maintainers are in accord with the essential ideas behind
+member are in accord with the essential ideas behind
 .  Reading the GNU Manifesto would also be
 a good idea.
 
 
-The process of registering as a developer is a process of verifying your
+The process of registering as a member is a process of verifying your
 identity and intentions, and checking your technical skills.  As the number of
 people working on  has grown to over
  and our systems are used in several
 very important places, we have to be careful about being compromised.
-Therefore, we need to verify new maintainers before we can give them accounts
+Therefore, we need to verify new members before we can give them accounts
 on our servers and let them upload packages.
 
 
@@ -193,7 +193,7 @@ cryptography even for authentication is forbidden then please contact us so we
 can make special arrangements.
 
 
-To apply as a new maintainer, you need an existing Debian Developer to support
+To apply as a new member, you need an existing Debian Developer to support
 your application (an advocate).  After you have
 contributed to Debian for a while, and you want to apply to become a registered
 developer, an existing developer with whom you have worked over the past months
@@ -206,14 +206,14 @@ register on our application
 page.  After you have signed up, your advocate has to confirm your
 application.  When your advocate has completed this step you will be assigned
 an Application Manager who will go with you through the necessary steps of the
-New Maintainer process.  You can always check your status on the applications status board.
 
 
 For more details, please consult New Members Corner at the
 Debian web site.  Make sure that you are familiar with the necessary steps of
-the

Bug#908890: developers-reference: As alioth is gone, replace references to Salsa

[Holger Wansing]

Control: tags -1 + pending

On Fri, 16 Nov 2018 20:31:18 +0100 Holger Wansing  wrote:
> 
> Tobias Frost created a merge request for this, under
> https://salsa.debian.org/debian/developers-reference/merge_requests/6
> 
> 
> Any objections against me merging this?

I have merged this now.

Tagging this bug as pending



-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#843966: developers-reference-fr: translation update

[Holger Wansing]

Control: tags -1 + pending


Holger Wansing  wrote:
> On Sun, 18 Nov 2018 13:38:02 +0100 Holger Wansing  
> wrote:
> > Hi Jean-Paul and Tobias,
> > 
> > On Thu, 30 Aug 2018 18:51:49 +0200 Tobias Frost  wrote:
> > > Hi,
> > > 
> > > I was a bit bug-triaging on developers-reference and found your patch.
> > > It seems that your patch has not been applied, but still the french
> > > translation seems to have advanced on in the pacakge.
> > > I unfortunatly do not speek French at all, so I cannot really tell what
> > > should be applied and what not...
> > > 
> > > Can you take a look and refresh the patch? 
> > > Many thanks!
> > > 
> > > tobi
> > 
> > @Jean-Paul: did you already start working on this? If not, I would commit a
> > new version of fr.po with manually merged French translations.
> 
> I got an updated file from Jean-Paul, and I will commit the manually merged
> changings (attached) from 2016 now.

Done.

Tagging this bug as pending.



-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#843966: developers-reference-fr: translation update

[Holger Wansing]

Hi Jean-Paul and Tobias,

On Thu, 30 Aug 2018 18:51:49 +0200 Tobias Frost  wrote:
> Hi,
> 
> I was a bit bug-triaging on developers-reference and found your patch.
> It seems that your patch has not been applied, but still the french
> translation seems to have advanced on in the pacakge.
> I unfortunatly do not speek French at all, so I cannot really tell what
> should be applied and what not...
> 
> Can you take a look and refresh the patch? 
> Many thanks!
> 
> tobi

@Jean-Paul: did you already start working on this? If not, I would commit a
new version of fr.po with manually merged French translations.

@Tobias: maybe you received an answer from Jean-Paul via PM?



Holger




-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#657107: developers-reference : styles of handwriting are Bold

[Holger Wansing]

Control: tags -1 + wontfix


Nobuhiro Iwamatsu  wrote:
> A.2.2. debdiff,  A.5.3. dcut and A.6.7. dpkg-depcheck styles of
> handwriting are Bold.
> It seems that it will be changed into bold if it surrounds by .
> Commands other than these are surrounded by .
> Therefore, the style of handwriting is not Bold.

As I see it, this is only a very minor difference, and thus not worse a change.


So tagging this bug as wontfix.

Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#900679: nmu: Migrating developers-reference to Salsa and minor updates

[Holger Wansing]

Aurélien COUDERC  wrote:
> I would like to NMU developers-reference for migrating the repository to Salsa
> and a couple of minor changes.
> 
> The complete changelog would be :
> 
> developers-reference (3.4.19+nmu1) UNRELEASED; urgency=medium
> 
>   [ Aurélien COUDERC ]
>   * Non-maintainer upload.
>   * Move repository to Salsa, update Vcs-* fields.
>   * d/control: Bump Standards-Version to 4.1.4, no change needed.
>   * Fix CSS text color to avoid the HTML version being unreadable when
> using a light on dark default browser stylesheet.

The above changings were committed in the meantime, so the target of the
OP and this bug is closed.

Thus this bug can closed, right?
Any objections? (There was some discussion about maintenance of the
devref package in this bug, however this does not deserve keeping this
bug open, or it should be renamed accordingly.)


Holger



-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#908890: developers-reference: As alioth is gone, replace references to Salsa

[Holger Wansing]

Tobias Frost created a merge request for this, under
https://salsa.debian.org/debian/developers-reference/merge_requests/6


Any objections against me merging this?

Holger



-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#818850: developers-reference: Join the two chapters about the 'default' field

[Holger Wansing]

Control: tags -1 + pending


Holger Wansing  wrote:
> Control: tags -1 - pending
> 
> 
> Maintainers, what do you think about
> https://salsa.debian.org/debian/developers-reference/merge_requests/8/diffs 
> to 
> fix this bug?
> 
> Any objections against me merging this?
> 

Since there were no objections, I have merged this into master now.

Tagging this bug as pending.


Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#690750: Broken links in developers-reference as published on the Debian's website

[Holger Wansing]

Control: tags -1 + pending

Lev Lamberov  wrote:
> Вс 04 ноя 2018 @ 12:00 Holger Wansing :
> 
> > Proposal: maybe the easiest way to make all variants (view via debian.org
> > and opened locally) work correctly, would be to change it this way:
> >
> > "This page is also available in
> > https://www.debian.org/doc/devel-manuals#devref;>French, 
> > German, 
> > Italian, Russian, and Japanese."
> >
> > since the links on that page are fine and can be linked from everywhere
> > with one single static link.
> > Of course, there are still some corner cases which do not work (for 
> > example, 
> > when you have the packages installed locally, you cannot switch from the 
> > local english to the local german version via that links, and when you
> > have no internet connection, you also get an irritating situation), but 
> > most 
> > usecases should be fine, and it would be an improvement compared to the 
> > current situation, where all links do not work!
> >
> > Would fix #690750 and #912724.
> >
> > Comments?
> 
> In case one take a look into other documentation (togather with its
> translation), one will not find any such notes and links to
> translations. Maybe there's no need in such note in "Debian Developer's
> Reference"? Or at least no need in explicit links? What about to remove
> it completely or change text to something like "This documentation is
> also available in some other languages"?

I have committed this now like this, while 'some  other languages' is a link
to https://www.debian.org/doc/devel-manuals#devref


Tagging these bugs as pending

Holger




-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#690750: Bug#912724: Broken links in developers-reference as published on the Debian's website

[Holger Wansing]

Hi,

Am Montag, 12. November 2018 schrieb Lev Lamberov:
> Вс 04 ноя 2018 @ 12:00 Holger Wansing :
> 
> > Proposal: maybe the easiest way to make all variants (view via debian.org
> > and opened locally) work correctly, would be to change it this way:
> >
> > "This page is also available in
> > https://www.debian.org/doc/devel-manuals#devref;>French, 
> > German, 
> > Italian, Russian, and Japanese."
> >
> > since the links on that page are fine and can be linked from everywhere
> > with one single static link.
> > Of course, there are still some corner cases which do not work (for 
> > example, 
> > when you have the packages installed locally, you cannot switch from the 
> > local english to the local german version via that links, and when you
> > have no internet connection, you also get an irritating situation), but 
> > most 
> > usecases should be fine, and it would be an improvement compared to the 
> > current situation, where all links do not work!
> >
> > Would fix #690750 and #912724.
> >
> > Comments?
> 
> In case one take a look into other documentation (togather with its
> translation), one will not find any such notes and links to
> translations. Maybe there's no need in such note in "Debian Developer's
> Reference"? Or at least no need in explicit links? What about to remove
> it completely or change text to something like "This documentation is
> also available in some other languages"?

Yes, I had also thought about that.
Another benefit would be, that we don't need to rephrase
the sentence, when new translations are added or outdated
onces removed.
But I still would like to make that a link, for usability.
 

Holger

-- 
Sent from my Jolla phone
http://www.jolla.com/

Bug#690750: Broken links in developers-reference as published on the Debian's website

[Holger Wansing]

Hi,

Holger Wansing  wrote:
> 
> Proposal: maybe the easiest way to make all variants (view via debian.org
> and opened locally) work correctly, would be to change it this way:
> 
> "This page is also available in
> https://www.debian.org/doc/devel-manuals#devref;>French, German, 
> Italian, Russian, and Japanese."
> 
> since the links on that page are fine and can be linked from everywhere
> with one single static link.
> Of course, there are still some corner cases which do not work (for example, 
> when you have the packages installed locally, you cannot switch from the 
> local english to the local german version via that links, and when you
> have no internet connection, you also get an irritating situation), but most 
> usecases should be fine, and it would be an improvement compared to the 
> current situation, where all links do not work!
> 
> Would fix #690750 and #912724.
> 
> 
> Comments?

If noone objects shortly, I will commit this next weekend then.


Holger


-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#690750: Broken links in developers-reference as published on the Debian's website

[Holger Wansing]

Hi,

Lev Lamberov  wrote:
> Hi Holger,
> 
> thanks for your attention to the bug report, but my report was about a
> different issue. Let me explain.

When looking into all this, it's even more complicated ...

> First, let's take a look at developers-reference as it pubished on the
> Debian's website. Say, in English [web-en]. It incorrectly links to
> translations as index.{fr,de,it,ru,jp}.en.html, such files do not exist.
> Any other translation, say, French [web-fr] links to translations as
> index.{de,it,ru,jp}.fr.html, such files do not exist.
> 
> [web-en] https://www.debian.org/doc/manuals/developers-reference/index.en.html
> 
> [web-fr] https://www.debian.org/doc/manuals/developers-reference/index.fr.html

... since there are links on the website which work, and others do not:

On https://www.debian.org/doc/devel-manuals#devref (on the wegpage itself)
all links are correct and working.
However, when going into the document itself under for example
https://www.debian.org/doc/manuals/developers-reference/index.en.html
we can find links to
https://www.debian.org/doc/manuals/developers-reference/index.fr.en.html
https://www.debian.org/doc/manuals/developers-reference/index.de.en.html
and so on. So re-writing the links inside the document does not work correctly,
while the ones on the wegpages itself are fine.


> Second, let's take a look at developers-reference package. All links
> there are correct, that is in _any_ language links point to
> index.{fr,de,it,ru,jp}.html.

That might be correct so far.
However, if you install those packages on your local machine (let's say the
english and the french package), the links inside that documents do not
work:
when you open the english document locally, the link to the german version
is file:///usr/share/doc/developers-reference/index.de.html
however that file does not exist, it is stored as
usr/share/doc/developers-reference-de/index.html


> Third, let's take a look at developers-reference source code. In English
> we currently have as follows:
> 
> 
> If you want to print this reference, you should use the  url="developers-reference.pdf">pdf version.  This page is also
> available in French,  url="index.de.html">German,  url="index.it.html">Italian,  url="index.ru.html">Russian, and  url="index.ja.html">Japanese.
> 
> 




Proposal: maybe the easiest way to make all variants (view via debian.org
and opened locally) work correctly, would be to change it this way:

"This page is also available in
https://www.debian.org/doc/devel-manuals#devref;>French, German, 
Italian, Russian, and Japanese."

since the links on that page are fine and can be linked from everywhere
with one single static link.
Of course, there are still some corner cases which do not work (for example, 
when you have the packages installed locally, you cannot switch from the 
local english to the local german version via that links, and when you
have no internet connection, you also get an irritating situation), but most 
usecases should be fine, and it would be an improvement compared to the 
current situation, where all links do not work!

Would fix #690750 and #912724.


Comments?

Holger


-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#912724: Broken links in developers-reference as published on the Debian's website

[Holger Wansing]

Control: reassign 912724 www.debian.org

Lev Lamberov  wrote:
> Hi Holger,
> 
> thanks for your attention to the bug report, but my report was about a
> different issue. Let me explain.
> 
[]
> 
> Let me stress that my report is _not_ about links to English, or links
> in English. It is about _broken_ links in _any_ developers-reference as
> published on the Debian's website. So, my bug report is about
> www.debian.org, not developers-reference. Please, reconsider it and
> reassign #912724 to www.debian.org.

Yes, you are right. I did not read your report careful enough. Sorry.
Reassigning back to www.debian.org


Holger

-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#690750: Bug#912724: www.debian.org: wrong links to translations of "Debian Developer's Reference"

[Holger Wansing]

Control: reassign 912724 developers-reference

Lev Lamberov  wrote:
> Package: www.debian.org
> Severity: normal
> Tags: l10n
> 
> Dear Maintainer,
> 
> Debian Developer's Reference on the Debian's website [reference]
> contains wrong links to translations of the documantation. That is,
> French translation is linked as index.fr.en.html (where it should be
> index.fr.html) and so on. The same problem holds for translations,
> that is French translation [reference-fr] links to Italian as
> index.it.fr.html (where it should be index.it.html).
> 
> [reference-en] 
> https://www.debian.org/doc/manuals/developers-reference/index.en.html
> 
> [reference-fr] 
> https://www.debian.org/doc/manuals/developers-reference/index.fr.html
> 
> I guess the problem is with the content negotiation, since there's no
> such problems both in the source code of the documentation and in the

This has already been reported (years ago :-( ) in 
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=690750

(and: no, there's no content negotiation involved here, that's static links;
thus reassigning to package)


I have already proposed a fix there, too.

@hideki: any objections against me committing the patch from
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=690750#17 ?



Holger


-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#818850: developers-reference: Join the two chapters about the 'default' field

[Holger Wansing]

Control: tags -1 - pending


Maintainers, what do you think about
https://salsa.debian.org/debian/developers-reference/merge_requests/8/diffs to 
fix this bug?

Any objections against me merging this?

BTW: I'm removing the pending tag for now, since this is not yet committed 
(at least not to master)



Holger


-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#690750: developers-reference: no link to English manual

[Holger Wansing]

Control: tags -1 + patch

hwans...@mailbox.org wrote:
> I have attached a patch to fix this, so that it says:

The patch is now attached.


Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/index.dbk b/index.dbk
index ea3d33f..2068638 100644
--- a/index.dbk
+++ b/index.dbk
@@ -86,14 +86,13 @@ it by writing to the .
 
 
 If you want to print this reference, you should use the pdf version.  This page is also
-available in French, pdf version.  This manual is
+available in English,
+French, German, Italian, Russian, and Japanese.
-
 
 
 

Bug#690750: developers-reference: no link to English manual

[Holger Wansing]

Control: tags -1 + patch

Hideki Yamane  wrote:
>  Now it's index.html says "This page is also available in French, German
>  and Japanese." and link to each language. However, this line is same in
>  each language.
> 
>  So, non-English manuals doesn't have a link to original English manual.

I have attached a patch to fix this, so that it says:

"This manual is available in English, French, German, Italian, Russian, and 
Japanese."

That way, the same text would work for all translations :-)

I can commit this, if you agree.


Holger


-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

Bug#905930: www.debian.org: Duplication of text in webpage https://www.debian.org/doc/manuals/developers-reference/ch04.en.html 4.6.5 "Debian 10, will be called buster and Debian 10 will be called bus

[Holger Wansing]

Control: reassign -1 developers-reference

Lucy Wayland  wrote:
> Package: www.debian.org
> Severity: minor

"text in webpage 
https://www.debian.org/doc/manuals/developers-reference/ch04.en.html 
4.6.5 "Debian 10, will be called buster and Debian 10 will be called buster." "


Re-assigning to the correct package

Holger

-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#905930: www.debian.org: Duplication of text in webpage https://www.debian.org/doc/manuals/developers-reference/ch04.en.html 4.6.5 "Debian 10, will be called buster and Debian 10 will be called bus

[Holger Wansing]

Control: tags -1 + pending


Holger Wansing  wrote:
> Control: reassign -1 developers-reference
> 
> Lucy Wayland  wrote:
> > Package: www.debian.org
> > Severity: minor
> 
> "text in webpage 
> https://www.debian.org/doc/manuals/developers-reference/ch04.en.html 
> 4.6.5 "Debian 10, will be called buster and Debian 10 will be called buster." 
> "
> 
> 
> Re-assigning to the correct package

I have fixed this in GIT.

Tagging this bug as pending



-- 

Created with Sylpheed 3.5.1 under 
D E B I A N   L I N U X   9   " S T R E T C H " .

Registered Linux User #311290 - https://linuxcounter.net/

Update URL for D-I Internals manual

[Holger Wansing]

[Please CC me on replies, I'm not subscribed to this list]


Hi,

after the Alioth shutdown, the D-I Internals manual is now available again
at dillon under https://d-i.debian.org/doc/internals/


You might want to apply the attached patch, to update this in the policy.


Regards
Holger

-- 
Holger Wansing 
PGP-Finterprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076
diff --git a/debian/changelog b/debian/changelog
index 875fc11..ec7b187 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,9 @@
+debian-policy (4.2.1.3) UNRELEASED; urgency=medium
+
+  * Update URL for D-I Internals manual because of Alioth shutdown.
+
+ -- Holger Wansing   Wed, 10 Oct 2018 10:07:11 +0200
+
 debian-policy (4.2.1.2) unstable; urgency=medium
 
   * README.md: drop mention of 'dbnpolicy' UNIX group, which has now been
diff --git a/locales/ja/LC_MESSAGES/ch-scope.po b/locales/ja/LC_MESSAGES/ch-scope.po
index d62d0f8..1b12fd4 100644
--- a/locales/ja/LC_MESSAGES/ch-scope.po
+++ b/locales/ja/LC_MESSAGES/ch-scope.po
@@ -92,7 +92,7 @@ msgid ""
 "udebs (stripped-down binary packages used by the Debian Installer) do not"
 " comply with all of the requirements discussed here. See the `Debian "
 "Installer internals manual "
-"<https://d-i.alioth.debian.org/doc/internals/ch03.html>`_ for more "
+"<https://d-i.debian.org/doc/internals/ch03.html>`_ for more "
 "information about them."
 msgstr ""
 
diff --git a/policy/ch-scope.rst b/policy/ch-scope.rst
index 557018e..406d39a 100644
--- a/policy/ch-scope.rst
+++ b/policy/ch-scope.rst
@@ -48,7 +48,7 @@ is intended for local use only.
 udebs (stripped-down binary packages used by the Debian Installer) do
 not comply with all of the requirements discussed here. See the `Debian
 Installer internals
-manual <https://d-i.alioth.debian.org/doc/internals/ch03.html>`_ for
+manual <https://d-i.debian.org/doc/internals/ch03.html>`_ for
 more information about them.
 
 .. _s1.2:
diff --git a/policy/locale/ja/LC_MESSAGES/ch-scope.po b/policy/locale/ja/LC_MESSAGES/ch-scope.po
index b416b0b..ab083eb 100644
--- a/policy/locale/ja/LC_MESSAGES/ch-scope.po
+++ b/policy/locale/ja/LC_MESSAGES/ch-scope.po
@@ -116,12 +116,12 @@ msgid ""
 "udebs (stripped-down binary packages used by the Debian Installer) do not"
 " comply with all of the requirements discussed here. See the `Debian "
 "Installer internals manual "
-"<https://d-i.alioth.debian.org/doc/internals/ch03.html>`_ for more "
+"<https://d-i.debian.org/doc/internals/ch03.html>`_ for more "
 "information about them."
 msgstr ""
 "udebs (Debian インストーラで用いる機能限定版のバイナリパッケージ) "
 "は、以下で説明されている要求事項に必ずしも従っていません。詳細は"
-"`Debian Installer internals manual <https://d-i.alioth.debian.org/doc/internals/ch03.html>`_ "
+"`Debian Installer internals manual <https://d-i.debian.org/doc/internals/ch03.html>`_ "
 "を参照してください。"
 
 #: ../../ch-scope.rst:57

Bug#818850: developers-reference: two chapters regarding the 'default' field

[Holger Wansing]

Package: developers-reference


In the developers-reference from git today, there are two chapters 
regarding the 'default' field, that is 6.5.4.4 and 6.5.4.5.
See 
https://www.debian.org/doc/manuals/developers-reference/ch06.en.html#s6.5.4.4
and
https://www.debian.org/doc/manuals/developers-reference/ch06.en.html#s6.5.4.5
(these links are from the unstable version 3.4.17 though).

These two chapters should be merged into one chapter.


Greetings
Holger


-- 

Created with Sylpheed 3.5.0 under
D E B I A N   L I N U X   8 . 0   " J E S S I E " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#818847: developers-reference: PDF generation faulty, headlines crippled

[Holger Wansing]

Package: developers-reference


Due to two bugs (one is broken fonts, one is the broken dvipdfmx for 
t1 fonts; see https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=796952 )
there might be problems with generating pdf documents, the headlines content
may be crippled, not readable.

This has alredy been reported for the release-notes, and it has been fixed
there in the meantime for Jessie (see above bug #796952), but today I noticed 
that the developers-reference is probably affected too.

I have build the Debian Developer's Reference here locally today, on a Jessie
system, and it has crippled headlines too in the pdf variant, it looks
identically, so it seems also affected.

Maybe this is not a problem since developers-reference builds fine on 
unstable systems?
I wonder if it might be a problem nevertheless, since when Stretch is
released, the www-master machine, which builds the docs for the Debian
website, is still running Jessie, and in that moment it will generate
crippled PDFs for developers-reference ... ?!


Greetings
Holger


-- 

Created with Sylpheed 3.5.0 under
D E B I A N   L I N U X   8 . 0   " J E S S I E " .

Registered Linux User #311290 - https://linuxcounter.net/

Bug#817914: developers-reference: globally change "new maintainer" into "new member"

[Holger Wansing]

Package: developers-reference
Version: 3.4.17
Severity: wishlist


Based on the GR 
https://www.debian.org/vote/2010/vote_002 -- Debian project members --
welcome non-packaging contributors
the New Maintainer process has been renamed into New Member process.
See https://www.debian.org/devel/join/newmaint.en.html

In the developers-reference, there are several occurrences of "maintainer" in 
this context, which should be replaced with "member", or maybe "contributor",
depending on the context.

If you agree with this, I could provide a patch...


Holger


-- 

Created with Sylpheed 3.5.0 under
D E B I A N   L I N U X   8 . 0   " J E S S I E " .

Registered Linux User #311290 - https://linuxcounter.net/