Processed: Re: Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Debian Bug Tracking System]

Processing control commands:

> tag -1 + pending
Bug #968226 [debian-policy] Move documentation of Build-Depends alternative 
selection out of footnote
Added tag(s) pending.

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

Bug#968226: Move documentation of Build-Depends alternative selection out of footnote

[Sean Whitton]

control: tag -1 + pending

On Sun 10 Sep 2023 at 10:45am -07, Russ Allbery wrote:

> Russ Allbery  writes:
>
>> This patch from a while back is still waiting for one more second before
>> it can be merged for the next Policy release.  It previously got one
>> second from Wouter.  I revised the patch to mention the experimental
>> suite as well as the backports suites.
>
> Argh, wrong patch, sorry.  Here is the one that was actually updated to
> include experimental.

Seconded and applied.  I think the whole thing might be non-normative,
but certainly the mere addition of experimental is.

> --
> Russ Allbery (r...@debian.org)  
>
>>From 7ee49f6c892d6057b9a0d2f9eb84ff0f35d1d436 Mon Sep 17 00:00:00 2001
> From: Russ Allbery 
> Date: Tue, 20 Sep 2022 19:11:54 -0700
> Subject: [PATCH] Improve alternative build dependency discussion
>
> Alternatives in build dependencies are normally (except for
> backports) handled specially by autobuilders to try to maintain
> consistent builds.  This was documented in Policy, but in a
> footnote that people often didn't see.
>
> Move this text into the main body of the discussion of build
> dependencies and reword it for additional clarity.  Add a pointer
> to this discussion where alternative dependencies are introduced.
> ---
>  policy/ch-relationships.rst | 61 +++--
>  1 file changed, 45 insertions(+), 16 deletions(-)
>
> diff --git a/policy/ch-relationships.rst b/policy/ch-relationships.rst
> index 5074428..ffafbf1 100644
> --- a/policy/ch-relationships.rst
> +++ b/policy/ch-relationships.rst
> @@ -15,7 +15,10 @@ control fields of the package, which declare dependencies 
> on other
>  packages, the package names listed may also include lists of alternative
>  package names, separated by vertical bar (pipe) symbols ``|``. In such a
>  case, that part of the dependency can be satisfied by any one of the
> -alternative packages.  [#]_
> +alternative packages. (Alternative dependencies in ``Build-Depends``,
> +``Build-Depends-Indep``, and ``Build-Depends-Arch`` are interpreted
> +specially by Debian autobuilders. See :ref:`Relationships between source
> +and binary packages ` for more details.)
>  
>  All of the fields may restrict their applicability to particular versions
>  of each named package. This is done in parentheses after each individual
> @@ -620,6 +623,47 @@ earlier for binary packages) in order to invoke the 
> targets in
>  ``Build-Conflicts-Arch`` fields must be satisfied when these targets
>  are invoked.
>  
> +Alternative dependencies are allowed in the ``Build-Depends``,
> +``Build-Depends-Indep``, and ``Build-Depends-Arch`` fields, but Debian's
> +autobuilders normally discard the dependencies after the first. This is
> +done to give alternative dependencies a consistent interpretation that
> +reduces the risk of inconsistencies between repeated builds. If, for
> +example, the first-listed dependency would normally be available but is
> +temporarily not installable, the autobuilder fails rather than install a
> +subsequent dependency that may significantly change the behavior of the
> +package.
> +
> +More specifically, Debian autobuilders perform the following
> +transformation on alternative dependencies in the ``Build-Depends``,
> +``Build-Depends-Indep``, and ``Build-Depends-Arch`` fields:
> +
> +#. Discard any alternatives that are restricted to architectures that do
> +   not match the host architecture.
> +#. Discard any alternatives specifying different package names than the
> +   now-first alternative. (Alternatives specifying the same package name
> +   are kept to permit relationships such as ``foo (<= x) | foo (>= y)``.)
> +
> +For example, an autobuilder for the ``amd64`` architecture would treat the
> +following dependency::
> +
> +foo-special [armhf] | foo (<= 4) | foo (>= 4.2) | bar
> +
> +as if it were::
> +
> +foo (<= 4) | foo (>= 4.2)
> +
> +The normal effect is to use only the first alternative that is valid on
> +the relevant architecture and fail if that alternative is not installable.
> +
> +While this rule for build dependencies may limit the usefulness of
> +alternatives, they can still be used to provide flexibility when building
> +the package outside of Debian's autobuilders.
> +
> +The autobuilders for the Debian backports and experimental suites do not
> +perform this transformation and instead use the same dependency resolution
> +rules as normal package installations to choose which alternative
> +dependency to install.
> +
>  .. _s-built-using:
>  
>  Additional source packages used to build the binary - ``Built-Using``
> @@ -666,21 +710,6 @@ requirements to retain the referenced source packages.  
> It should not
>  be added solely as a way to locate packages that need to be rebuilt
>  against newer versions of their build dependencies.
>  
> -.. [#]
> -   While ``Build-Depends``, ``Build-Depends-Indep`` and
> -   ``Build-Depends-

Bug#945269: debian-policy: packages should use tmpfiles.d(5) to create directories below /var

[Sean Whitton]

Hello,

On Sun 17 Sep 2023 at 10:52am -07, Russ Allbery wrote:

> I don't see how shipping empty directories in a deb package affects this
> in any way.  You're going to have to be considerably more specific about
> what invariant is being violated or what error you're expecting.
>
> One of the key things that I'm stuck on, and which you haven't addressed
> that I've seen, is that you're talking here about a system managed with a
> normal package manager, and therefore running all maintainer scripts.  The
> maintainer scripts under this tmpfiles.d proposal will create directories
> and files in /var, because the whole point is that systemd-tmpfiles is run
> from postinst.  But you are saying that creating directories and files in
> /var with the package manager will break this configuration.  I'm missing
> something here.  There's nothing special about dpkg creating the directory
> versus postinst creating the directory.  So far as I can tell, the only
> important part is that the directory be registered in tmpfiles.d (or a
> service unit) so that it can be recreated when needed.

Something which I don't think has been mentioned yet is that we
explicitly permit the local administrator to nuke /usr/share/doc, even
though that is a similar sort of inconsistency between the dpkg db and
the filesystem as the ones that are bothering Luca.

> I understand that you are trying to do something new, and you are worried
> that this will interfere with it, but so far you have not been able to
> explain any way in which this *would* cause you problems.  You just don't
> like the vibes.  And I hear that, and sometimes that sort of bad feeling
> is a valuable architectural clue, but in this case you're really going to
> have to be more specific because I'm not seeing it.
>
> Also, we clearly cannot ship a system without /var *now* because oodles of
> other packages put things there, so a lot of work is left to do before
> this is a technical vision that Debian can implement, if we do indeed
> decide to implement it.  Policy can always change later; perhaps by the
> time that we're ready to implement this vision, dpkg will have a way of
> registering files managed by tmpfiles.d and there's no reason to ship the
> empty directories in the package.  So theoretical future problems are not
> very persuasive to me at this stage, particularly if you can't be specific
> about what those problems would be.
>
>> [...]
>
> I understand that you would like to finish this, but Debian so far has not
> even decided to *start* this, so while I'm willing to take this into
> account when writing Policy, it's not a controlling design principle.  If
> you get an agreement in Debian that this is something we're going to work
> towards, then it will become a significant factor in evaluating Policy
> changes.
>
> I'm really trying to meet you halfway here by adopting and fleshing out
> proposals that you're putting forward primarily for a project that Debian
> isn't currently doing, but which have clear other benefits regardless of
> whether we do the factory reset project.  I don't want to argue over end
> goals when we can agree on intermediate steps regardless of the end goal.
> But I really want to emphasize here that we are not *currently* writing
> Policy to support factory reset because there is no decision in Debian yet
> that we are supporting factory reset.
>
> This is not directly relevant to this bug, but for the record, if you want
> Debian to support factory reset, one good way to make that more likely is
> to write a DEP with the details of precisely what that would mean, roughly
> what sorts of things would need to change in packaging, and a list of what
> the benefits would be.  I personally think a lot of the benefits are
> rather compelling, but no one has yet made a proper case for it in Debian.
> You and Marco and a few other people just write email messages on other
> topics that treat the desirability of factory reset as a foregone
> conclusion, or mention a few benefits in passing and without specifics,
> which of course is fine for casual discussion but which is not a real
> attempt at persuasion and doesn't get us closer to making a real decision.
>
> In other words, this is advice that I constantly give myself because I am
> very bad at this and have to be reminded repeatedly: stop arguing with
> people about specifics and use that energy to write down a design with a
> justification.  It will make the arguments much less annoying and
> repetitive, because a lot of the repetition is because everyone else is
> sadly incapable of reading your mind and doesn't understand what you are
> assuming is well-known.

I very much agree.  It also seems worth mentioning that if we are able
to support factory-reset, we will also want to minimise how much it gets
in the way of people who have no interest in that sort of feature --
most of our classic Debian desktop power users, I suspect (which
includes most DDs).

Russ, I think th

Bug#915583: about html_static_path

[Sean Whitton]

Hello,

On Thu 15 Feb 2024 at 11:44pm +01, Holger Wansing wrote:

> 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.

Attached is the patch I prepared, which I couldn't get to work.  Maybe
you can see what is wrong.  Thanks!

-- >8 --
From: =?UTF-8?q?St=C3=A9phane=20Blondon?= 
Date: Mon, 27 Nov 2023 23:36:06 +0100
Subject: [PATCH] New Debian-specific Sphinx style

---
 debian/changelog  |   3 ++
 debian/control|   1 +
 policy/conf.py.in |   5 ++-
 policy/debian.css | 103 ++
 4 files changed, 111 insertions(+), 1 deletion(-)
 create mode 100644 policy/debian.css

diff --git a/debian/changelog b/debian/changelog
index ffa0f8b..6d04491 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -14,6 +14,9 @@ debian-policy (4.6.2.1) UNRELEASED; urgency=medium
   package metadata.
   * Update Installed-Size algorithm used by dpkg (Closes: #793499).
 
+  [ Stéphane Blondon ]
+  * New Debian-specific Sphinx style (Closes: #915583).
+
  -- Russ Allbery   Sat, 09 Sep 2023 15:27:27 -0700
 
 debian-policy (4.6.2.0) unstable; urgency=medium
diff --git a/debian/control b/debian/control
index a98b425..ebb3c3f 100644
--- a/debian/control
+++ b/debian/control
@@ -17,6 +17,7 @@ Build-Depends:
  libxml2-utils,
  links | elinks,
  python3-sphinx,
+ python3-sphinx-rtd-theme,
  sphinx-common (>= 1.6.5),
  sphinx-intl,
  texinfo,
diff --git a/policy/conf.py.in b/policy/conf.py.in
index d516d7b..86bc1ac 100755
--- a/policy/conf.py.in
+++ b/policy/conf.py.in
@@ -84,7 +84,7 @@ 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
@@ -92,6 +92,9 @@ html_theme = 'nature'
 #
 # html_theme_options = {}
 
+# 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@"
 
diff --git a/policy/debian.css b/policy/debian.css
new file mode 100644
index 000..7f0981b
--- /dev/null
+++ b/policy/debian.css
@@ -0,0 +1,103 @@
+/* Debian Cascading stylesheet for Sphinx */
+
+div.related {
+background-color: #C70036;
+}
+
+.rst-content h1, .rst-content h2, .rst-content h3, .rst-content h4, 
.rst-content h5, .rst-content h6 {
+color: #C70036;
+}
+
+.wy-nav-top {
+background-color: #C70036;
+}
+
+.wy-side-nav-search {
+background-color: #C70036;
+}
+
+.rst-content a:link {
+color: #0035C7;
+text-decoration: none;
+}
+.rst-content a:visited {
+color: #00207A;
+text-decoration: none;
+}
+.rst-content a:link:hover {
+color: #00207A;
+text-decoration: underline;
+}
+
+
+/* Table in content */
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+white-space: normal;
+}
+
+.rst-content table.docutils, .wy-table-bordered-all {
+width: 100%;
+}
+
+.wy-table-responsive table.docutils thead tr {
+background-color: #C70036;
+border: 1px solid black;
+color: black;
+}
+
+.wy-table-responsive table.docutils thead tr:hover {
+color: #fcfcfc;
+}
+
+.wy-table-responsive table.docutils tbody tr:hover {
+background-color:#66;
+color: #FF;
+}
+
+.rst-content table.docutils:not(.field-list) tbody tr:hover:nth-child(2n-1), 
.wy-table-backed, .wy-table-odd td, .wy-table-striped tr:nth-child(2n-1) td {
+background-color:#66;
+}
+
+/* Previous and next buttons */
+
+.rst-footer-buttons .btn:hover {
+text-decoration: none !important;
+}
+
+/* Version release more readable */
+
+.wy-side-nav-search > div.version {
+color: #FCFCFC;
+}
+
+/* Infos blocks */
+
+div.warning {
+border: 1px dashed #EFF500;
+background-color: #eff50030;
+}
+
+div.note {
+border: 1px dashed blue;
+background-color: #ff30;
+
+}
+
+.warning, .note {
+margin-left: 1em;
+margin-right: 1em;
+}
+
+@media (max-width: 5in), (max-device-width: 5in){
+.warning, .note {
+margin-left: 0.5em;
+margin-right: 0.5em;
+}
+}
+
+/* Notes */
+
+html.writer-html5 .rst-content aside.citation, html.writer-html5 .rst-content 
aside.footnote, html.writer-html5 .rst-content div.citation {
+display: block;
+}
-- 
Sean Whitton


signature.asc
Description: 

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