Re: Bug#1067079: Clarify that policy on a technology does not implicitly mandate that technology

[Russ Allbery]

Josh Triplett  writes:

> Nonetheless, if the Policy editors are opposed to documenting something
> despite it being collectively known to be the case, and do not feel that
> any possible wording change would change that position, then I will not
> push for it further.

I have already suggested a wording change that I would be happy to review
and that I think would be much more likely to accomplish your goals.
Document the other way of doing things that you would like Policy to
mention.  It doesn't have to be long; in many cases, one paragraph with
some man page references would be sufficient to get people pointed in the
right direction.

In an ideal world, I think people *should* prefer to do things in one of
the ways that Policy documents doing them, even if other ways of doing
them would be acceptable.  That's how we get a more consistent
distribution.  This requires documenting our preferences, which seems like
a good thing all around.

-- 
Russ Allbery (r...@debian.org)  

Re: Bug#1067079: Clarify that policy on a technology does not implicitly mandate that technology

[Josh Triplett]

Sean Whitton wrote:
> On Tue 26 Mar 2024 at 10:11am -06, Sam Hartman wrote:
> > I tend to agree with  Sean that your rationale is not convincing.
> > It sounds like you want to use policy as a stick to hit people
> > over the head and say "policy is not a stick."
>
> This was basically my concern.

This feels like a painful mischaracterization of what I said. I don't
want to use policy as a stick. I want to make policy less usable as a
stick.

Nonetheless, if the Policy editors are opposed to documenting something
despite it being collectively known to be the case, and do not feel that
any possible wording change would change that position, then I will not
push for it further.

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-based documents work, we need relative symlinks pointing from the
+# manual's _static/css/* and _static/fonts/* files to targets inside of
+# doc/html-theme/ in the www build tree.
+# Those targets are populated from the sphi

Processed: issue with Debian-style html theme for sphinx-based documents

[Debian Bug Tracking System]

Processing control commands:

> reassign 1064593 www.debian.org
Bug #1064593 [debian-policy] debian-policy: missing static resources for 
www.debian.org policy page
Bug reassigned from package 'debian-policy' to 'www.debian.org'.
No longer marked as found in versions debian-policy/4.6.2.1.
Ignoring request to alter fixed versions of bug #1064593 to the same values 
previously set

-- 
1064593: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1064593
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems