Bug#915583: debian sphinx styling: second attempt

[Stéphane Blondon]

Hello,

I've done a new version. It's based on 'sphinx_rtd_theme' theme. So,
to build the site, the package 'python3-sphinx-rtd-theme' requires to
be added to dependencies. A new file 'debian.css' is specific to set
some colors and renderings.

Reusing 'Read the docs' theme allows to have a responsive design automatically.

The theme could be modified more but it could be considered as a first
step which is already usable.

There are temporary demos available:
 - for debian-policy: http://stephane.yaal.fr/tmp/policy/
 - for (draft sphinx) release-notes: http://stephane.yaal.fr/tmp/release-notes/

What do you think about it?

-- 
Stéphane

Re: Does iproute2 moving config files to /usr/lib violate section 10.7.2?

[Bill Allombert]

On Thu, Sep 14, 2023 at 04:01:05PM +0200, Daniel Gröber wrote:
> Hello debian-policy,
> 
> iproute2 has moved it's config files that were traditionally at
> /etc/iproute2 to /usr/lib/iproute2 due to an upstream change. I've tried to
> convince the maintainer(s) that this is a bad idea in Bug#1051577, when
> this was shot down I filed Bug#1051847 as severity:serious on the basis of
> Debian policy section 10.7.2 section 10.7.2. "Configuration files /
> Location" which states as follows:
> 
> > Any configuration files created or used by your package must reside
> > in /etc.
> 
> Pretty clear cut in my reading, however this was promptly shot down by
> Bastian  with the justification:
> 
> > No, it does not.  The files in /usr are defaults.  Those should be copied
> > to /etc for modification, which is config.
> 
> Am I going nuts? Somehow long established unix convention and usability
> doesn't matter anymore and policy doesn't mean what it says?

The idea is that files in /usr/ are default files that can be 
overrided or supplemented by a configuration file in /etc/ with the same name.
When properly documented, this is a very good scheme since that make update of
configuration file easier.
The kpathsea system of TeX is an extreme version of that scheme that allow
several level of override simultaneously.

For a simple example, popularity-contest ships
/usr/share/popularity-contest/default.conf as default file
which is overrided by the configuration file
/etc/popularity-contest.conf

/usr/share/popularity-contest/default.conf says PARTICIPATE="no"
and users that want to participate set PARTICIPATE="yes" in
/etc/popularity-contest.conf (through debconf) to override it.

It is recommended that /etc/ carry dummy configuration files that provide
information on the default file they override.

Of course changing the configuration files scheme is a different issue and need
to be done carefully so that users understand what is expected of them.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Re: Does iproute2 moving config files to /usr/lib violate section 10.7.2?

[Russ Allbery]

Daniel Gröber  writes:

>> Any configuration files created or used by your package must reside
>> in /etc.

> Pretty clear cut in my reading, however this was promptly shot down by
> Bastian  with the justification:

Configuration file has a very specific meaning in Policy: it's a file that
the local system administrator changes in order to configure the software.
If the file is not intended to be modified to configure the software, it's
not a configuration file, even if it contains configuration defaults.
See:

https://www.debian.org/doc/debian-policy/ch-files.html#configuration-files

although it doesn't make this as clear as it should be because it was
written before split configurations became common.

That's because the main point of distinguishing configuration files (in
addition to collecting them in /etc for the use of things like etckeeper)
is to ensure that we handle the modifications correctly, don't lose them
during upgrades, etc.  Static files that aren't modified by the local
administrator don't need that special handling.

Having the configuration *defaults* exist as a static file on disk in
/usr/lib isn't really that different than having the configuration
defaults exist hard-coded into the binary, which has been common for many
years.  Either way, what Debian requires is that the defaults be modified
by putting files into /etc, so as long as that continues to be true, this
is satisfying Debian's configuration requirement.  This isn't that
different than long-standing UNIX precedent, as seen in packages such as
postfix or INN or any number of other programs that support configuration
files in /etc but have a large number of hard-coded defaults that apply if
those files are missing or don't set that option.

I should say explicitly that none of this addresses the *preference*
argument between people who prefer to have the defaults in /usr and
overrides in /etc, and people who prefer to have all of the settings in
/etc so that they are readily visible for modification.  Some people
prefer one, some people prefer the other, and both sides feel strongly
about it and probably won't convince the other side.  But this conflict
has existed for essentially forever in the form of defaults that are
hard-coded into the binary and not expressed in the sample configuration
file, so it's not really a new conflict, and I think it's more transparent
to have defaults in a separate file in /usr than hard-coded into a
compiled binary.

I do understand why folks who prefer the "all settings in one modifyable
file in /etc" are annoyed when packages move to the split configuration
model with a file of defaults in /usr, but it's not something that Policy
requires one way or the other and there are vigorous advocates of both
methods.

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

Re: Does iproute2 moving config files to /usr/lib violate section 10.7.2?

[Sam Hartman]

> "Daniel" == Daniel Gröber  writes:


>> Any configuration files created or used by your package must
>> reside in /etc.

It's fine for packages to store defaults outside of /etc.  But that 's
only true if you can override those defaults by placing a file in /etc.

Does iproute2 moving config files to /usr/lib violate section 10.7.2?

[Daniel Gröber]

Hello debian-policy,

iproute2 has moved it's config files that were traditionally at
/etc/iproute2 to /usr/lib/iproute2 due to an upstream change. I've tried to
convince the maintainer(s) that this is a bad idea in Bug#1051577, when
this was shot down I filed Bug#1051847 as severity:serious on the basis of
Debian policy section 10.7.2 section 10.7.2. "Configuration files /
Location" which states as follows:

> Any configuration files created or used by your package must reside
> in /etc.

Pretty clear cut in my reading, however this was promptly shot down by
Bastian  with the justification:

> No, it does not.  The files in /usr are defaults.  Those should be copied
> to /etc for modification, which is config.

Am I going nuts? Somehow long established unix convention and usability
doesn't matter anymore and policy doesn't mean what it says?

I'd appreciate any input and advice on how to proceed here since I'm new to
contributing to Debian outside of packaging :)

Thanks,
--Daniel


signature.asc
Description: PGP signature