Bug#983657: debian-policy: weaken manual page requirement

[Bill Allombert]

On Sun, Feb 28, 2021 at 08:58:44PM +0100, Helmut Grohne wrote:
> On Sun, Feb 28, 2021 at 10:53:20AM -0700, Sean Whitton wrote:
> > Can you post a patch just doing the moving manpages to dependencies part
> > and indicate that you are seeking seconds?  Then we can get that
> > applied.
> 
> I call for seconds on:
> 
> --- a/policy/ch-docs.rst
> +++ b/policy/ch-docs.rst
> @@ -12,9 +12,9 @@
>  "cat page".
>  
>  Each program, utility, and function should have an associated manual
> -page included in the same package. It is suggested that all
> -configuration files also have a manual page included as well. Manual
> -pages for protocols and other auxiliary things are optional.
> +page included in the same package or a dependency. It is suggested that
> +all configuration files also have a manual page included as well.
> +Manual pages for protocols and other auxiliary things are optional.
>  
>  If no manual page is available, this is considered as a bug and should
>  be reported to the Debian Bug Tracking System (the maintainer of the

What matter, I think, is that if a program is installed, then its manual
is available. There are various ways to achieve that, even though I do
not think Recommends cut it.

Cheers,
Bill

Bug#983657: debian-policy: weaken manual page requirement

[Sean Whitton]

control: tag -1 + pending

Hello,

On Sun 28 Feb 2021 at 08:58PM +01, Helmut Grohne wrote:

> I call for seconds on:
>
> --- a/policy/ch-docs.rst
> +++ b/policy/ch-docs.rst
> @@ -12,9 +12,9 @@
>  "cat page".
>
>  Each program, utility, and function should have an associated manual
> -page included in the same package. It is suggested that all
> -configuration files also have a manual page included as well. Manual
> -pages for protocols and other auxiliary things are optional.
> +page included in the same package or a dependency. It is suggested that
> +all configuration files also have a manual page included as well.
> +Manual pages for protocols and other auxiliary things are optional.
>
>  If no manual page is available, this is considered as a bug and should
>  be reported to the Debian Bug Tracking System (the maintainer of the

Seconded, and I'll mark this bug as pending; if discussion on your other
issue gets to the point where wording is proposed, please clone this
bug.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#983657: debian-policy: weaken manual page requirement

[Christoph Berg]

Re: Helmut Grohne
> On Sun, Feb 28, 2021 at 10:53:20AM -0700, Sean Whitton wrote:
> > Can you post a patch just doing the moving manpages to dependencies part
> > and indicate that you are seeking seconds?  Then we can get that
> > applied.
> 
> I call for seconds on:
> 
> --- a/policy/ch-docs.rst
> +++ b/policy/ch-docs.rst
> @@ -12,9 +12,9 @@
>  "cat page".
>  
>  Each program, utility, and function should have an associated manual
> -page included in the same package. It is suggested that all
> -configuration files also have a manual page included as well. Manual
> -pages for protocols and other auxiliary things are optional.
> +page included in the same package or a dependency. It is suggested that
> +all configuration files also have a manual page included as well.
> +Manual pages for protocols and other auxiliary things are optional.
>  
>  If no manual page is available, this is considered as a bug and should
>  be reported to the Debian Bug Tracking System (the maintainer of the

Seconded.

Christoph


signature.asc
Description: PGP signature

Bug#983657: debian-policy: weaken manual page requirement

[Russ Allbery]

Helmut Grohne  writes:

> I call for seconds on:

> --- a/policy/ch-docs.rst
> +++ b/policy/ch-docs.rst
> @@ -12,9 +12,9 @@
>  "cat page".
>  
>  Each program, utility, and function should have an associated manual
> -page included in the same package. It is suggested that all
> -configuration files also have a manual page included as well. Manual
> -pages for protocols and other auxiliary things are optional.
> +page included in the same package or a dependency. It is suggested that
> +all configuration files also have a manual page included as well.
> +Manual pages for protocols and other auxiliary things are optional.
>  
>  If no manual page is available, this is considered as a bug and should
>  be reported to the Debian Bug Tracking System (the maintainer of the

Seconded.

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

Bug#983657: debian-policy: weaken manual page requirement

[Helmut Grohne]

On Sun, Feb 28, 2021 at 10:53:20AM -0700, Sean Whitton wrote:
> Can you post a patch just doing the moving manpages to dependencies part
> and indicate that you are seeking seconds?  Then we can get that
> applied.

I call for seconds on:

--- a/policy/ch-docs.rst
+++ b/policy/ch-docs.rst
@@ -12,9 +12,9 @@
 "cat page".
 
 Each program, utility, and function should have an associated manual
-page included in the same package. It is suggested that all
-configuration files also have a manual page included as well. Manual
-pages for protocols and other auxiliary things are optional.
+page included in the same package or a dependency. It is suggested that
+all configuration files also have a manual page included as well.
+Manual pages for protocols and other auxiliary things are optional.
 
 If no manual page is available, this is considered as a bug and should
 be reported to the Debian Bug Tracking System (the maintainer of the

Helmut

Bug#983657: debian-policy: weaken manual page requirement

[Sean Whitton]

Hello,

On Sun 28 Feb 2021 at 05:41PM +01, Helmut Grohne wrote:

> If we cannot build consensus around that second part, so be it. But
> maybe the other part (moving manual pages to dependencies) can reach
> consensus?

Can you post a patch just doing the moving manpages to dependencies part
and indicate that you are seeking seconds?  Then we can get that
applied.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#983657: debian-policy: weaken manual page requirement

[Helmut Grohne]

On Sun, Feb 28, 2021 at 11:58:08AM +0100, Bill Allombert wrote:
> On Sun, Feb 28, 2021 at 08:29:21AM +0100, Helmut Grohne wrote:
> > So this is actually asking for two distinct things:
> >  * Allow moving manual pages to dependencies
> >  * Allow demoting such dependencies to recommends
> > 
> > A possible wording in ch-docs.rst could be:
> >  Each program, utility, and function should have an associated manual
> > -page included in the same package. It is suggested that all
> > +page included in the same package or one of its dependencies or
> > +recommended packages. It is suggested that all
> >  configuration files also have a manual page included as well. Manual
> >  pages for protocols and other auxiliary things are optional.
> > 
> > What do you think?
> 
> The goal is to avoid program to be installed but not their manpages,
> so generally I do not find Recommends to be enough.

If we cannot build consensus around that second part, so be it. But
maybe the other part (moving manual pages to dependencies) can reach
consensus?

Helmut

Bug#983657: debian-policy: weaken manual page requirement

[Bill Allombert]

On Sun, Feb 28, 2021 at 08:29:21AM +0100, Helmut Grohne wrote:
> So this is actually asking for two distinct things:
>  * Allow moving manual pages to dependencies
>  * Allow demoting such dependencies to recommends
> 
> A possible wording in ch-docs.rst could be:
>  Each program, utility, and function should have an associated manual
> -page included in the same package. It is suggested that all
> +page included in the same package or one of its dependencies or
> +recommended packages. It is suggested that all
>  configuration files also have a manual page included as well. Manual
>  pages for protocols and other auxiliary things are optional.
> 
> What do you think?

The goal is to avoid program to be installed but not their manpages,
so generally I do not find Recommends to be enough.
I would object to manual page being moved to a -doc package even if they
are Recommended, because -doc packages tend to be large while manpages
are usually short and do not require pdf/html readers.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#983657: debian-policy: weaken manual page requirement

[Helmut Grohne]

Package: debian-policy
Version: 4.5.1.0
Severity: wishlist

I think that the Debian policy is unreasonably strict in its manual page
requirement. While the common case is that manual pages are small and
should be included in the same package, occasionally they are numerous
and moving them to a separate package makes sense. Other times, there
already is a -common or -doc package and including them there would be
possible without increasing the package count. Doing so often allows
demoting dependencies to Build-Depends-Indep and thus reducing bootstrap
problems.

I therefore think that the policy should explicitly allow manual pages
to be shipped in a dependency. We can see that this already is
established practice from this non-exhaustive list:
 * aptitude -> aptitude-common
 * assaultcube -> assaultcube-data
 * aumix -> aumix-common
 * auto-multiple-choice -> auto-multiple-choice-common
 * binutils -> binutils-common
 * bitlbee -> bitlbee-common
 * bup -> bup-doc (recommends)
 * cpp-10 -> cpp-10-doc (no relation, license re
 * critterding -> crittering-common
 * grass-core -> grass-doc
 * x3270 -> 3270-common

Beyond this, I think that a manual page does not warrant a strong
dependency given that man-db is not essential. Rather a recommendation
should be strong enough. I'm not sure whether this view is universal
though.

So this is actually asking for two distinct things:
 * Allow moving manual pages to dependencies
 * Allow demoting such dependencies to recommends

A possible wording in ch-docs.rst could be:
 Each program, utility, and function should have an associated manual
-page included in the same package. It is suggested that all
+page included in the same package or one of its dependencies or
+recommended packages. It is suggested that all
 configuration files also have a manual page included as well. Manual
 pages for protocols and other auxiliary things are optional.

What do you think?

Helmut