Bug#910783: Remove doc-base recommendation

[Ansgar]

Sean Whitton writes:
> On Sun 14 Jul 2019 at 10:22AM +02, Ansgar wrote:
>> How should we continue with this issue?
>
> Thank you for following up.
>
> I still do not see any positive reason for deleting documentation which
> might be helpful to someone, especially when discussion in the bug has
> indicated that people are doing work which might come to depend on
> doc-base.

Deleting it has the minor advantage of there being less stuff to read.
But I'm fine with keeping the reference if it is still helpful for
others.

So your proposed change looks good to me.  Thanks.

Ansgar

> Therefore I would like to propose the following change:
>
> diff --git a/policy/ch-customized-programs.rst 
> b/policy/ch-customized-programs.rst
> index 529aa66..dbba4fc 100644
> --- a/policy/ch-customized-programs.rst
> +++ b/policy/ch-customized-programs.rst
> @@ -151,9 +151,8 @@ web servers and web applications in the Debian system.
>  
> Web Applications should try to avoid storing files in the Web
> Document Root. Instead they should use the /usr/share/doc/package
> -   directory for documents and register the Web Application via the
> -   doc-base package. If access to the web document root is unavoidable
> -   then use
> +   directory for documents. If access to the web document root is
> +   unavoidable then use
>  
> ::
>  
> diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
> index 6e0c020..fa1428f 100644
> --- a/policy/ch-opersys.rst
> +++ b/policy/ch-opersys.rst
> @@ -976,11 +976,11 @@ Here is an example of a wrapper script for this purpose:
>  Registering Documents using doc-base
>  
>  
> -The doc-base package implements a flexible mechanism for handling and
> -presenting documentation. The recommended practice is for every Debian
> -package that provides online documentation (other than just manual
> -pages) to register these documents with doc-base by installing a
> -doc-base control file in ``/usr/share/doc-base/``.
> +The doc-base package implements a mechanism for handling and
> +presenting documentation. Debian packages that provides online
> +documentation (other than just manual pages) may register these
> +documents with doc-base by installing a doc-base control file in
> +``/usr/share/doc-base/``.
>  
>  Please refer to the documentation that comes with the doc-base package
>  for information and details.

Bug#910783: Remove doc-base recommendation

[Russ Allbery]

Sean Whitton  writes:

> Therefore I would like to propose the following change:

This looks good to me, and I agree that this thread has shown a consensus
that lack of doc-base registration should not be considered a bug, given
our belief that it is not widely used.

Seconded.

> diff --git a/policy/ch-customized-programs.rst 
> b/policy/ch-customized-programs.rst
> index 529aa66..dbba4fc 100644
> --- a/policy/ch-customized-programs.rst
> +++ b/policy/ch-customized-programs.rst
> @@ -151,9 +151,8 @@ web servers and web applications in the Debian system.
>  
> Web Applications should try to avoid storing files in the Web
> Document Root. Instead they should use the /usr/share/doc/package
> -   directory for documents and register the Web Application via the
> -   doc-base package. If access to the web document root is unavoidable
> -   then use
> +   directory for documents. If access to the web document root is
> +   unavoidable then use
>  
> ::
>  
> diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
> index 6e0c020..fa1428f 100644
> --- a/policy/ch-opersys.rst
> +++ b/policy/ch-opersys.rst
> @@ -976,11 +976,11 @@ Here is an example of a wrapper script for this purpose:
>  Registering Documents using doc-base
>  
>  
> -The doc-base package implements a flexible mechanism for handling and
> -presenting documentation. The recommended practice is for every Debian
> -package that provides online documentation (other than just manual
> -pages) to register these documents with doc-base by installing a
> -doc-base control file in ``/usr/share/doc-base/``.
> +The doc-base package implements a mechanism for handling and
> +presenting documentation. Debian packages that provides online
> +documentation (other than just manual pages) may register these
> +documents with doc-base by installing a doc-base control file in
> +``/usr/share/doc-base/``.
>  
>  Please refer to the documentation that comes with the doc-base package
>  for information and details.

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

Bug#910783: Remove doc-base recommendation

[Sean Whitton]

Hello,

On Sun 14 Jul 2019 at 10:22AM +02, Ansgar wrote:

> How should we continue with this issue?

Thank you for following up.

I still do not see any positive reason for deleting documentation which
might be helpful to someone, especially when discussion in the bug has
indicated that people are doing work which might come to depend on
doc-base.

However, it is clear that we do not think a lack of doc-base
registration is a bug of severity greater than wishlist, which is what
the current Policy wording implies.

Therefore I would like to propose the following change:

diff --git a/policy/ch-customized-programs.rst 
b/policy/ch-customized-programs.rst
index 529aa66..dbba4fc 100644
--- a/policy/ch-customized-programs.rst
+++ b/policy/ch-customized-programs.rst
@@ -151,9 +151,8 @@ web servers and web applications in the Debian system.
 
Web Applications should try to avoid storing files in the Web
Document Root. Instead they should use the /usr/share/doc/package
-   directory for documents and register the Web Application via the
-   doc-base package. If access to the web document root is unavoidable
-   then use
+   directory for documents. If access to the web document root is
+   unavoidable then use
 
::
 
diff --git a/policy/ch-opersys.rst b/policy/ch-opersys.rst
index 6e0c020..fa1428f 100644
--- a/policy/ch-opersys.rst
+++ b/policy/ch-opersys.rst
@@ -976,11 +976,11 @@ Here is an example of a wrapper script for this purpose:
 Registering Documents using doc-base
 
 
-The doc-base package implements a flexible mechanism for handling and
-presenting documentation. The recommended practice is for every Debian
-package that provides online documentation (other than just manual
-pages) to register these documents with doc-base by installing a
-doc-base control file in ``/usr/share/doc-base/``.
+The doc-base package implements a mechanism for handling and
+presenting documentation. Debian packages that provides online
+documentation (other than just manual pages) may register these
+documents with doc-base by installing a doc-base control file in
+``/usr/share/doc-base/``.
 
 Please refer to the documentation that comes with the doc-base package
 for information and details.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#910783: Remove doc-base recommendation

[Ansgar]

Sean Whitton writes:
> On Thu 11 Oct 2018 at 12:57PM +0500, Andrey Rahmatullin wrote:
>
>> It seems to me that the consensus is that doc-base is not actually useful and
>> so 9.10. Registering Documents using doc-base can be dropped.
>
> We shouldn't drop it because then the doc-base registrations in existing
> packages would be undocumented.
>
> Instead, if there is indeed consensus, we should change it so that it
> no longer says that doc-base registration is recommended.

9.10 only refers to the doc-base package for information how the
doc-base registrations work.  So I don't think anything would be list
here.

How should we continue with this issue?

Ansgar

Bug#910783: Remove doc-base recommendation

[Holger Levsen]

On Wed, May 15, 2019 at 09:07:53AM +0200, Ansgar Burchardt wrote:
> > We need a cross-distro cross-desktop standard for an index of
> > docs before we can move on from doc-base like we did with menu.
> I don't think so: we can just remove doc-base without providing a
> replacement at the same time too.
> 
> Personally I don't know anyone using doc-base (probably most don't even
> know it exists).  If doc-base has indeed no users (or very few users),
> it just creates work for maintainers for no real benefit.
> 
> As [1] says, doc-base had 20+ years to get adopted.  I think it is fair
> to say that it failed to do so.
 
fully agreed. (and as said previously in this bug, I still have no idea
how to make use of doc-base...)


-- 
tschau,
Holger

---
   holger@(debian|reproducible-builds|layer-acht).org
   PGP fingerprint: B8BF 5413 7B09 D35C F026 FE9D 091A B856 069A AA1C


signature.asc
Description: PGP signature

Bug#910783: Remove doc-base recommendation

[Ansgar Burchardt]

Paul Wise writes:
> On Thu, 11 Oct 2018 17:32:52 -0700 Sean Whitton wrote:
>> Instead, if there is indeed consensus, we should change it so that it
>> no longer says that doc-base registration is recommended.
>
> We need a cross-distro cross-desktop standard for an index of
> docs before we can move on from doc-base like we did with menu.

I don't think so: we can just remove doc-base without providing a
replacement at the same time too.

Personally I don't know anyone using doc-base (probably most don't even
know it exists).  If doc-base has indeed no users (or very few users),
it just creates work for maintainers for no real benefit.

As [1] says, doc-base had 20+ years to get adopted.  I think it is fair
to say that it failed to do so.

  [1] https://bugs.debian.org/910783#13

Ansgar

Bug#910783: Remove doc-base recommendation

[Paul Wise]

On Thu, 11 Oct 2018 17:32:52 -0700 Sean Whitton wrote:

> Instead, if there is indeed consensus, we should change it so that it
> no longer says that doc-base registration is recommended.

We need a cross-distro cross-desktop standard for an index of
docs before we can move on from doc-base like we did with menu.

-- 
bye,
pabs

https://wiki.debian.org/PaulWise



signature.asc
Description: This is a digitally signed message part

Bug#910783: Remove doc-base recommendation

[Adam D. Barratt]

On 2018-10-12 10:16, Bill Allombert wrote:

On Thu, Oct 11, 2018 at 01:04:52PM +0100, Ian Jackson wrote:
Andrey Rahmatullin writes ("Bug#910783: Remove doc-base 
recommendation"):

> Package: debian-policy
> Version: 4.2.1.2
> Severity: normal
>
> It seems to me that the consensus is that doc-base is not actually useful and
> so 9.10. Registering Documents using doc-base can be dropped.
>
> lintian has an I: possible-documentation-but-no-doc-base-registration tag, 
with
> 1872 emitted currently: 
https://lintian.debian.org/tags/possible-documentation-
> but-no-doc-base-registration.html
>
I suggest that instead of abandoning it, we should bump the lintian
message to a warning.


Is not I: (info) even lower priority than W: (warning) ?
I do not think it is displayed by default:
from lintian(1):

   -I, --display-info
   Display informational ("I:") tags as well.  They are
normally suppressed.


I believe you've misunderstood - Ian is suggesting *raising* the level 
of the tag, not lowering it.


Regards,

Adam

Bug#910783: Remove doc-base recommendation

[Bill Allombert]

On Thu, Oct 11, 2018 at 01:04:52PM +0100, Ian Jackson wrote:
> Andrey Rahmatullin writes ("Bug#910783: Remove doc-base recommendation"):
> > Package: debian-policy
> > Version: 4.2.1.2
> > Severity: normal
> > 
> > It seems to me that the consensus is that doc-base is not actually useful 
> > and
> > so 9.10. Registering Documents using doc-base can be dropped.
> > 
> > lintian has an I: possible-documentation-but-no-doc-base-registration tag, 
> > with
> > 1872 emitted currently: 
> > https://lintian.debian.org/tags/possible-documentation-
> > but-no-doc-base-registration.html
> > 
> I suggest that instead of abandoning it, we should bump the lintian
> message to a warning.

Is not I: (info) even lower priority than W: (warning) ?
I do not think it is displayed by default:
from lintian(1):

   -I, --display-info
   Display informational ("I:") tags as well.  They are normally 
suppressed.

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#910783: Remove doc-base recommendation

[Bill Allombert]

On Thu, Oct 11, 2018 at 06:10:43PM -0700, Russ Allbery wrote:
> Stuart Prescott  writes:
> 
> > In counterpoint, I'll add to that 4169 packages register 5318 sets of
> > documents in doc-base. To me, that says that we've got a lot of packages
> > who are advertising their documentation this way.
> 
> I wish I had some feel for how many people were actually using doc-base as
> a client, though.  How many users actually run the tools and use them to
> find documentation, and is it successful for them?
> 
> I dutifully provide doc-base registrations for all the documentation in
> all of my packages, but I think in all the time I've been using Debian
> I've only run the tool as a user maybe twice, and then only to check
> whether my package documentation showed up.  So the fact that my packages
> all have doc-base registrations doesn't indicate those registrations are
> useful, necessarily.

I do the same. On the other hand, it is useful for QA because lintian
will complain if the documents advertised in doc-base do not exist
anymore, so you know if the documentation build process has some issue.

[[ But that sad truth is that the real issue is not that users do not use
doc-base, but rather that they do not use the documentation provided in
Debian in the first place, and instead reach to Google to locate some
documentation online (which might not be for the same version,
leading to conflict with upstream) ]]

Cheers,
-- 
Bill. 

Imagine a large red swirl here. 

Bug#910783: Remove doc-base recommendation

[Holger Levsen]

On Thu, Oct 11, 2018 at 06:10:43PM -0700, Russ Allbery wrote:
> I wish I had some feel for how many people were actually using doc-base as
> a client, though.  How many users actually run the tools and use them to
> find documentation, and is it successful for them?

to give a data-point: I have no idea how to use doc-base.

If I search documentation I use a shell to cd into /usr/share/doc/$pkg
and run ls there. Or use apropos term. Or I search the web.

How do I use doc-base?


-- 
cheers,
Holger

---
   holger@(debian|reproducible-builds|layer-acht).org
   PGP fingerprint: B8BF 5413 7B09 D35C F026 FE9D 091A B856 069A AA1C


signature.asc
Description: PGP signature

Bug#910783: Remove doc-base recommendation

[Russ Allbery]

Stuart Prescott  writes:

> In counterpoint, I'll add to that 4169 packages register 5318 sets of
> documents in doc-base. To me, that says that we've got a lot of packages
> who are advertising their documentation this way.

I wish I had some feel for how many people were actually using doc-base as
a client, though.  How many users actually run the tools and use them to
find documentation, and is it successful for them?

I dutifully provide doc-base registrations for all the documentation in
all of my packages, but I think in all the time I've been using Debian
I've only run the tool as a user maybe twice, and then only to check
whether my package documentation showed up.  So the fact that my packages
all have doc-base registrations doesn't indicate those registrations are
useful, necessarily.

> At the user-support BoF at the last DebConf, we also discussed how we
> could leverage doc-base files better to make documentation more easily
> discoverable. That is work-in-progress.

That sort of thing would be really cool.

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

Bug#910783: Remove doc-base recommendation

[Stuart Prescott]

> lintian has an I: possible-documentation-but-no-doc-base-registration tag,
> with 1872 emitted currently:
> https://lintian.debian.org/tags/possible-documentation-> 
> but-no-doc-base-registration.html

In counterpoint, I'll add to that 4169 packages register 5318 sets of 
documents in doc-base. To me, that says that we've got a lot of packages who 
are advertising their documentation this way.

At the user-support BoF at the last DebConf, we also discussed how we could 
leverage doc-base files better to make documentation more easily 
discoverable. That is work-in-progress.

cheers
Stuart

-- 
Stuart Prescotthttp://www.nanonanonano.net/   stu...@nanonanonano.net
Debian Developer   http://www.debian.org/ stu...@debian.org
GPG fingerprint90E2 D2C1 AD14 6A1B 7EBB 891D BBC1 7EBB 1396 F2F7

Bug#910783: Remove doc-base recommendation

[Sean Whitton]

Hello,

On Thu 11 Oct 2018 at 01:04PM +0100, Ian Jackson wrote:

> The problem with doc-base is not that it is a bad idea, it's that it's
> not comprehensive enough.
>
> I suggest that instead of abandoning it, we should bump the lintian
> message to a warning.

I'm not a Lintian maintainer, but I think I can safely say that we
definitely do not have project consensus for doing that.  It would be
considered a bug by a lot of people.

(I know that you treat Lintian warnings as less urgent than most other
people do, so I can understand why you would take bumping the severity
of the tag to be less related to the project consensus on the value of
doc-base.)

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#910783: Remove doc-base recommendation

[Sean Whitton]

Hello Andrey,

On Thu 11 Oct 2018 at 12:57PM +0500, Andrey Rahmatullin wrote:

> It seems to me that the consensus is that doc-base is not actually useful and
> so 9.10. Registering Documents using doc-base can be dropped.

We shouldn't drop it because then the doc-base registrations in existing
packages would be undocumented.

Instead, if there is indeed consensus, we should change it so that it
no longer says that doc-base registration is recommended.

> lintian has an I: possible-documentation-but-no-doc-base-registration tag, 
> with
> 1872 emitted currently: 
> https://lintian.debian.org/tags/possible-documentation-
> but-no-doc-base-registration.html

If we make the change, Lintian should probably stop emitting the tag.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Bug#910783: Remove doc-base recommendation

[Ian Jackson]

Andrey Rahmatullin writes ("Bug#910783: Remove doc-base recommendation"):
> Package: debian-policy
> Version: 4.2.1.2
> Severity: normal
> 
> It seems to me that the consensus is that doc-base is not actually useful and
> so 9.10. Registering Documents using doc-base can be dropped.
> 
> lintian has an I: possible-documentation-but-no-doc-base-registration tag, 
> with
> 1872 emitted currently: 
> https://lintian.debian.org/tags/possible-documentation-
> but-no-doc-base-registration.html
> 
> Note that doc-base is also mentioned in 11.5: "Web Applications should try to
> avoid storing files in the Web Document Root. Instead they should use the
> /usr/share/doc/package directory for documents and register the Web 
> Application
> via the doc-base package."

The problem with doc-base is not that it is a bad idea, it's that it's
not comprehensive enough.

I suggest that instead of abandoning it, we should bump the lintian
message to a warning.

Ian.

-- 
Ian JacksonThese opinions are my own.

If I emailed you from an address @fyvzl.net or @evade.org.uk, that is
a private address which bypasses my fierce spamfilter.