Debian Bug report logs - #7890
Policy manual contradicts itself about including docs or not.

Toggle useless messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Santiago Vila Doncel <sanvila@unex.es>

To: Debian Bugs <submit@bugs.debian.org>

Subject: Policy manual contradicts itself about including docs or not.

Date: Fri, 7 Mar 1997 10:10:00 +0100 (MET)

Package: dpkg-dev
Version: 1.4.0.8

The following paragraphs are somewhat contradictory:

1) If a package comes with large amounts of documentation which many
   users of the package will not require you should create a separate
   binary package to contain it, so that it does not take up disk space
   on the machines of users who do not need or want it installed.

2) If your package comes with extensive documentation in a markup format
   that can be converted to various other formats you should if possible
   ship HTML versions in the binary package, in the directory
   /usr/doc/package or its subdirectories.

What if both 1) and 2) are true? i.e. What if a package comes with large
amounts of documentation "which many users of the package will not
require" but it is in texinfo format ("that can be converted easily to
HTML")? This applies to most GNU programs.

I think policy should be clear about this, and state which is more
important, either 1) or 2)

[ In my opinion, it would be better to ship it in a different package,
this way user is free to install or not install the documentation. The
important thing here, I think, is that HTML docs should be "available",
which is not exactly the same as "included in the binary package". ]

BTW: My apologies to Manoj Srivastava and Ramos Gonçalves. I read 1) but I
didn't remember 2). This bug against policy should have been the first.

Message #10 received at 7890@bugs.debian.org (full text, mbox, reply):

From: J.R.Goncalves@reading.ac.uk

To: Santiago Vila Doncel <sanvila@unex.es>, 7890@bugs.debian.org

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: Fri, 07 Mar 1997 12:02:33 +0000

> 
> BTW: My apologies to Manoj Srivastava and Ramos Gonçalves. I read 1) but I
> didn't remember 2). This bug against policy should have been the first.
> 
> 

Santiago,

I also apologize for my reply to your bug report. I think you are that
the policy should be clear about it (1 and 2). In wget's case the
*.html is slightly over 100KBytes.

Thanks.

Ramos.

P.S.: Yesterday evening was not a good one, I suppose.


-- 
---     
     J. RAMOS Goncalves | E-mail: J.R.Goncalves@reading.ac.uk   
     Department of Physics - University of Reading - England - U.K.

Message #15 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Guy Maor <maor@ece.utexas.edu>

To: 7890@bugs.debian.org

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: 07 Mar 1997 12:48:21 -0600

Santiago Vila Doncel <sanvila@unex.es> writes:

> 1) If a package comes with large amounts of documentation which many
>    users of the package will not require you should create a separate
>    binary package to contain it, so that it does not take up disk space
>    on the machines of users who do not need or want it installed.
> 
> 2) If your package comes with extensive documentation in a markup format
>    that can be converted to various other formats you should if possible
>    ship HTML versions in the binary package, in the directory
>    /usr/doc/package or its subdirectories.
> 
> What if both 1) and 2) are true?

You're reading 2 too literally.  Change `the' to `a' in `ship HTML
versions in the binary package'.  2 is still satisfied if
documentation is shipped in a seperate package.

Btw, I do not think that 2 should apply to texinfo documentation.  Any
other documentation - latex, sgml, etc. should be converted to html.

A Netscape info reader plugin might be a cool thing to have.  It may
even be fairly trivial as we already have a Tcl/Tk reader and you can
get a Tcl/Tk Netscape plugin from Sun.


Guy

Message #20 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Manoj Srivastava <srivasta@datasync.com>

To: Guy Maor <maor@ece.utexas.edu>

Cc: 7890@bugs.debian.org, Christian Schwarz <schwarz@monet.m.isar.de>

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: 07 Mar 1997 14:28:50 -0600

Hi,

	I'll accept Guy's interpretation of policy (I still think that
 the `the' should be changed to `a' in the document, and some
 guideline provided to maintainers suggesting when the split to a
 separate doc package happens).

	However, I don't quite follow why this should not apply to
 texinfo documents _in particular_. I was under the impression that we
 are trying to unify documents under HTML, not HTML and/or info.

	If run time conversion is the issue, that should apply to all
 formats, not just texinfo. Or change the policy, and punt on
 unification of documentation. 

	manoj
>>"Guy" == Guy Maor <maor@ece.utexas.edu> writes:

Guy> Santiago Vila Doncel <sanvila@unex.es> writes:

>> 1) If a package comes with large amounts of documentation which
>> many users of the package will not require you should create a
>> separate binary package to contain it, so that it does not take up
>> disk space on the machines of users who do not need or want it
>> installed.
>> 
>> 2) If your package comes with extensive documentation in a markup
>> format that can be converted to various other formats you should if
>> possible ship HTML versions in the binary package, in the directory
>> /usr/doc/package or its subdirectories.
>> 
>> What if both 1) and 2) are true?

Guy> You're reading 2 too literally.  Change `the' to `a' in `ship
Guy> HTML versions in the binary package'.  2 is still satisfied if
Guy> documentation is shipped in a seperate package.

Guy> Btw, I do not think that 2 should apply to texinfo documentation.
Guy> Any other documentation - latex, sgml, etc. should be converted
Guy> to html.

Guy> A Netscape info reader plugin might be a cool thing to have.  It
Guy> may even be fairly trivial as we already have a Tcl/Tk reader and
Guy> you can get a Tcl/Tk Netscape plugin from Sun.

-- 
 Semper Fi, dude.
Manoj Srivastava               <url:mailto:srivasta@acm.org>
Mobile, Alabama USA            <url:http://www.datasync.com/%7Esrivasta/>

Message #25 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Guy Maor <maor@ece.utexas.edu>

To: 7890@bugs.debian.org

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: 07 Mar 1997 21:12:22 -0600

Manoj Srivastava <srivasta@datasync.com> writes:

> 	However, I don't quite follow why this should not apply to
>  texinfo documents _in particular_. I was under the impression that we
>  are trying to unify documents under HTML, not HTML and/or info.

To be honest, I'm not completely sure we shouldn't either.  Until we
have a clear decision one way or another, let's agree not to include
html versions of texinfo documentation.


Guy

Message #30 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Philippe Troin <phil@fifi.org>

To: Guy Maor <maor@ece.utexas.edu>, 7890@bugs.debian.org

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: Fri, 07 Mar 1997 20:17:29 -0800

On 07 Mar 1997 12:48:21 CST Guy Maor (maor@ece.utexas.edu) wrote:

> A Netscape info reader plugin might be a cool thing to have.  It may
> even be fairly trivial as we already have a Tcl/Tk reader and you can
> get a Tcl/Tk Netscape plugin from Sun.

Let me point out that the tcl/tk plugin from Sun comes with a license.
I feel the whole tcl/tk think drifting away from the free software world. 

Phil.

Message #35 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Philippe Troin <phil@fifi.org>

To: Guy Maor <maor@ece.utexas.edu>, 7890@bugs.debian.org

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: Fri, 07 Mar 1997 20:18:56 -0800

On 07 Mar 1997 21:12:22 CST Guy Maor (maor@ece.utexas.edu) wrote:

> Manoj Srivastava <srivasta@datasync.com> writes:
> 
> > 	However, I don't quite follow why this should not apply to
> >  texinfo documents _in particular_. I was under the impression that we
> >  are trying to unify documents under HTML, not HTML and/or info.
> 
> To be honest, I'm not completely sure we shouldn't either.  Until we
> have a clear decision one way or another, let's agree not to include
> html versions of texinfo documentation.

The problem with htmlified texinfo docs is that they cannot be reverted to info documentation. Texinfo files can be converted on the fly to html.
Some people prefer info over www. I do.

Phil.

Message #40 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Manoj Srivastava <srivasta@datasync.com>

To: Philippe Troin <phil@fifi.org>

Cc: 7890@bugs.debian.org, Christian Schwarz <schwarz@monet.m.isar.de>

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: 07 Mar 1997 23:50:26 -0600

Hi.

	I was not really suggesting replacing the info documentation
 (or the man pages, for that matter), I meant in addition to. The
 policy *does* say that HTML is our preferred format, so it should
 also be provided -- we need an authoritative interpretation of policy
 Bruce did say that HTML is important, but he was in favour of on the
 fly conversion, Maybe hte source format (sgml, texinfo) should always
 be supplied, to be converted into the preferred format on the fly
 (and kept around for a bit, like catman directories for nroff sources
 converted on the fly).

	As I said, The policy Manager should probably take control of
 this discussion (and move it to debian-devel) now.

	manoj
-- 
Manoj Srivastava               <url:mailto:srivasta@acm.org>
Mobile, Alabama USA            <url:http://www.datasync.com/%7Esrivasta/>

Message #45 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Philippe Troin <phil@fifi.org>

To: Manoj Srivastava <srivasta@datasync.com>

Cc: 7890@bugs.debian.org, Christian Schwarz <schwarz@monet.m.isar.de>

Subject: Re: Bug#7890: Policy manual contradicts itself about including docs or not.

Date: Fri, 07 Mar 1997 21:55:20 -0800

On 07 Mar 1997 23:50:26 CST Manoj Srivastava (srivasta@datasync.com) 
wrote:

> 	I was not really suggesting replacing the info documentation
>  (or the man pages, for that matter), I meant in addition to. The
>  policy *does* say that HTML is our preferred format, so it should
>  also be provided -- we need an authoritative interpretation of policy
>  Bruce did say that HTML is important, but he was in favour of on the
>  fly conversion, Maybe hte source format (sgml, texinfo) should always
>  be supplied, to be converted into the preferred format on the fly
>  (and kept around for a bit, like catman directories for nroff sources
>  converted on the fly).

Seconded !

> 	As I said, The policy Manager should probably take control of
>  this discussion (and move it to debian-devel) now.

Agreed too...

Phil.

Message #52 received at 7890@bugs.debian.org (full text, mbox, reply):

From: apharris@burrito.onshore.com (Adam P. Harris)

To: debian-policy@lists.debian.org

Cc: 7890@bugs.debian.org

Subject: Re: {PROPOSAL} #7890: Policy manual contradicts itself about including docs

Date: 22 Sep 1998 01:52:55 -0400

Manoj Srivastava <srivasta@datasync.com> writes:
> 	I also further stated:
>         I was not really suggesting replacing the info documentation
>     (or the man pages, for that matter), I meant in addition to. The
>     policy *does* say that HTML is our preferred format, so it should
>     also be provided

Yes, I mostly agree.  The *source* of the documentation should also be
shipped if possible (i.e., SGML, TeX).  This enables people to patch
documenatation and send in diffs; it also enables them to possibly
format the source into whatever media they like.

One other point which is possibly worth mentioning is that our
suggested format for native debian documentation is debiandoc-sgml.

.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>

Post-sig:  Manoj, shouldn't we be CC'ing the BTS for discussion?

Message #57 received at 7890@bugs.debian.org (full text, mbox, reply):

From: karlheg@inetarena.com (Karl M. Hegbloom)

To: apharris@burrito.onshore.com (Adam P. Harris)

Cc: debian-policy@lists.debian.org, 7890@bugs.debian.org

Subject: Re: {PROPOSAL} #7890: Policy manual contradicts itself about including docs

Date: 22 Sep 1998 20:22:16 -0700

>>>>> "Adam" == Adam P Harris <apharris@burrito.onshore.com> writes:

    Adam> Manoj Srivastava <srivasta@datasync.com> writes:
    >> I also further stated: I was not really suggesting replacing
    >> the info documentation (or the man pages, for that matter), I
    >> meant in addition to. The policy *does* say that HTML is our
    >> preferred format, so it should also be provided

    Adam> Yes, I mostly agree.  The *source* of the documentation
    Adam> should also be shipped if possible (i.e., SGML, TeX).  This
    Adam> enables people to patch documenatation and send in diffs; it
    Adam> also enables them to possibly format the source into
    Adam> whatever media they like.

 The source is available in the source package.

Message #62 received at 7890@bugs.debian.org (full text, mbox, reply):

From: Manoj Srivastava <srivasta@datasync.com>

To: Adam P Harris <apharris@burrito.onshore.com>, 7890@bugs.debian.org

Subject: Re: {PROPOSAL} #7890: Policy manual contradicts itself about including docs

Date: 23 Sep 1998 13:30:53 -0500

Hi,
>>"Adam" == Adam P Harris <apharris@burrito.onshore.com> writes:

 Adam> Manoj Srivastava <srivasta@datasync.com> writes:
 >> I also further stated:
 >> I was not really suggesting replacing the info documentation
 >> (or the man pages, for that matter), I meant in addition to. The
 >> policy *does* say that HTML is our preferred format, so it should
 >> also be provided

 Adam> Yes, I mostly agree.

	Does that mean you second the proposal? I suggest we implement
 this part of the proposal first, and leave the issue of the source of
 the documentation to another ptoposal, since that is turning out to
 be controversial.

	This proposal has only one second at the moment. I would like
 to see if there are others, and to move the non-controversial part of
 the proposal out of the way.

 Adam> The *source* of the documentation should also be
 Adam> shipped if possible (i.e., SGML, TeX).  This enables people to patch
 Adam> documenatation and send in diffs; it also enables them to possibly
 Adam> format the source into whatever media they like.

	I personally tend to agree, but I think this is grist for
 another proposal. 

	I shall retitle this bug and start the count down as soon as I
 get another second (I am saying that since it seems to me that the
 proposal I submitted is not controversial and can be handled quickly,
 reducing the number of open issues on policy).

	manoj
 not responsible for his sig generator
-- 
 You cannot see the wood for the trees. John Heywood
Manoj Srivastava  <srivasta@acm.org> <http://www.datasync.com/%7Esrivasta/>
Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05  CC 2D 27 12 1D F5 E8 6E

Message #67 received at 7890@bugs.debian.org (full text, mbox, reply):

From: "Adam P. Harris" <apharris@burrito.onshore.com>

To: Manoj Srivastava <srivasta@datasync.com>

Cc: 7890@bugs.debian.org

Subject: Re: {PROPOSAL} #7890: Policy manual contradicts itself about including docs

Date: Wed, 23 Sep 1998 15:00:47 -0400

Manoj Srivastava <srivasta@datasync.com> writes:
Adam> Yes, I mostly agree.

> 	Does that mean you second the proposal? I suggest we implement
> this part of the proposal first, and leave the issue of the source
> of the documentation to another ptoposal, since that is turning out
> to be controversial.

> 	This proposal has only one second at the moment. I would like
> to see if there are others, and to move the non-controversial part
> of the proposal out of the way.

Yes, I second.  I agree that the "controversial" part is worthy of
it's own report (and is low priority too).

.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>

Send a report that this bug log contains spam.