Re: QUESTION: Debian Policy: Manual pages

[Marvin Renich]

* Ian Jackson <[EMAIL PROTECTED]> [080224 09:18]:
> Bas Zoetekouw writes ("Re: QUESTION: Debian Policy: Manual pages"):
> > Why a recommends?  In order to satisfy the spirit of policy ("every
> > binary must have a man page") it would need to be a depends, imo.
> 
> I think the point of policy is to ensure the manpage exists, not to
> require that it be installed.
> 
> I think Suggests is the right dependency.  There is nothing wrong with
> installing a package without its documentation.
> 
> Ian.
> 

IANADD, but as a user, I disagree.  Policy [12.1] states:

  Each program, utility, and function should have an associated manual
  page included in the same package.

There is a big difference between a man page and more complete
documentation like a User Manual.

I _expect_ a man page for every executable.  A Depends, in my mind,
clearly satisfies the policy requirement, as the man page will be
available unless I use dpkg --force-* or some other drastic measure to
override the depends.  A Recommends may satisfy this (especially now
that apt defaults to installing them), but not quite as clearly.

Harshula, from your description it is not clear if c.tar.gz contains
substantial documentation beyond man pages.  If c.tar.gz contains very
little besides man pages and basic documentation, then Depend on c.deb,
and leave the man pages there.  If the tarball contains a lot of other
documentation, my preference as a user would be to have the man pages
moved into the binary a.deb and b.deb packages, and Recommend or Suggest
c.deb (without the man pages).

If you are making one source package with three binary packages, moving
the man pages to a different binary package is trivial.  If you are
making three separate source packages, I would still prefer to have the
man pages copied to the packages with their corresponding executable,
with a note in the README.Debian identifying the originating tarball.

I know this is more work (in the separate source package case), but as a
user I would appreciate not having to keep around a large documentation
package just to get man pages.

...Marvin


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: QUESTION: Debian Policy: Manual pages

[Ian Jackson]

Bas Zoetekouw writes ("Re: QUESTION: Debian Policy: Manual pages"):
> Why a recommends?  In order to satisfy the spirit of policy ("every
> binary must have a man page") it would need to be a depends, imo.

I think the point of policy is to ensure the manpage exists, not to
require that it be installed.

I think Suggests is the right dependency.  There is nothing wrong with
installing a package without its documentation.

Ian.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: QUESTION: Debian Policy: Manual pages

[Harshula]

Hi,

Answers:

a) Yes, they are *really* distributed in three separate tarballs.
b) The three tarballs are not released in sync.

Conclusion:

1) a.deb & b.deb shall depend on c.deb
2) a.deb & b.deb shall contain lintian overrides.

Thanks for the useful feedback!

[NOTE: If replying, please keep my email address in the TO/CC list]

cya,
#

On Fri, 2008-02-15 at 03:04 +1100, Harshula wrote:
> Hi,
> 
> re: http://www.debian.org/doc/debian-policy/ch-docs.html#s12.1
> ---
> 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.
> 
> 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
> package is allowed to write this bug report themselves, if they so
> desire). Do not close the bug report until a proper man page is
> available.[80]
> ---
> 
> Here's the example:
> 
> 1) a.tar.gz -> a.deb
> 2) b.tar.gz -> b.deb
> 3) c.tar.gz -> c.deb
> 
> c.tar.gz contains only documentation, including man pages for
> binaries/scripts in a.tar.gz and b.tar.gz.
> 
> Since c.deb contains all the man pages, running lintian on a.deb results
> in:
> ---
> W: m17n-db: binary-without-manpage usr/bin/m17n-db
> N:
> N:   Each binary in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games
> should
> N:   have a manual page
> N:   
> N:   Note, that though the `man' program has the capability to check for
> N:   several program names in the NAMES section, each of these programs
> N:   should have its own manual page (a symbolic link to the appropriate
> N:   manual page is sufficient) because other manual page viewers such
> as
> N:   xman or tkman don't support this.
> N:   
> N:   Refer to Policy Manual, section 12.1 for details.
> N:
> ---
> 
> What is the recommended way to deal with this scenario?
> 
> cya,
> #


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: QUESTION: Debian Policy: Manual pages

[Cyril Brulebois]

On 14/02/2008, Russ Allbery wrote:
> I thought that tag in lintian already had a note that you should add
> an override if the man pages are shipped in a different package on
> which this package has a dependency. Apparently I was just imagining
> things.

ISTR it's the case for icons in desktop/menu files.

-- 
Cyril Brulebois


pgpGmD9xFI6pW.pgp
Description: PGP signature

Re: QUESTION: Debian Policy: Manual pages

[Bas Zoetekouw]

Hi Josselin!

You wrote:

> Le vendredi 15 février 2008 à 03:04 +1100, Harshula a écrit :
> > 1) a.tar.gz -> a.deb
> > 2) b.tar.gz -> b.deb
> > 3) c.tar.gz -> c.deb
> > 
> > c.tar.gz contains only documentation, including man pages for
> > binaries/scripts in a.tar.gz and b.tar.gz.
> 
> Then a and b should Recommend: c, regardless of how the upstream
> tarballs are packaged. All the rest is superfluous. Just ignore the
> lintian warning or add an override, 

Why a recommends?  In order to satisfy the spirit of policy ("every
binary must have a man page") it would need to be a depends, imo.

-- 
Kind regards,
Bas Zoetekouw.


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: QUESTION: Debian Policy: Manual pages

[Russ Allbery]

Harshula <[EMAIL PROTECTED]> writes:

> Since c.deb contains all the man pages, running lintian on a.deb results
> in:
> ---
> W: m17n-db: binary-without-manpage usr/bin/m17n-db
> N:
> N:   Each binary in /usr/bin, /usr/sbin, /bin, /sbin or /usr/games
> should
> N:   have a manual page
> N:   
> N:   Note, that though the `man' program has the capability to check for
> N:   several program names in the NAMES section, each of these programs
> N:   should have its own manual page (a symbolic link to the appropriate
> N:   manual page is sufficient) because other manual page viewers such
> as
> N:   xman or tkman don't support this.
> N:   
> N:   Refer to Policy Manual, section 12.1 for details.
> N:
> ---
>
> What is the recommended way to deal with this scenario?

I thought that tag in lintian already had a note that you should add an
override if the man pages are shipped in a different package on which this
package has a dependency.  Apparently I was just imagining things.

Such a note will be present in the next release.

-- 
Russ Allbery ([EMAIL PROTECTED])   


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: QUESTION: Debian Policy: Manual pages

[Josselin Mouette]

Le vendredi 15 février 2008 à 03:04 +1100, Harshula a écrit :
> 1) a.tar.gz -> a.deb
> 2) b.tar.gz -> b.deb
> 3) c.tar.gz -> c.deb
> 
> c.tar.gz contains only documentation, including man pages for
> binaries/scripts in a.tar.gz and b.tar.gz.

Then a and b should Recommend: c, regardless of how the upstream
tarballs are packaged. All the rest is superfluous. Just ignore the
lintian warning or add an override, 

Cheers,
-- 
 .''`.
: :' :  We are debian.org. Lower your prices, surrender your code.
`. `'   We will add your hardware and software distinctiveness to
  `-our own. Resistance is futile.


signature.asc
Description: Ceci est une partie de message	numériquement signée

Re: QUESTION: Debian Policy: Manual pages

[Felipe Sateler]

Harshula wrote:

> Hi,
> 
> re: http://www.debian.org/doc/debian-policy/ch-docs.html#s12.1
> ---
> 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.
> 
> 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
> package is allowed to write this bug report themselves, if they so
> desire). Do not close the bug report until a proper man page is
> available.[80]
> ---
> 
> Here's the example:
> 
> 1) a.tar.gz -> a.deb
> 2) b.tar.gz -> b.deb
> 3) c.tar.gz -> c.deb
> 
> c.tar.gz contains only documentation, including man pages for
> binaries/scripts in a.tar.gz and b.tar.gz.

> What is the recommended way to deal with this scenario?

If the three tarballs are released in sync, it may be possible to repack all
three as one source tarball for debian.

-- 

  Felipe Sateler


-- 
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]

Re: QUESTION: Debian Policy: Manual pages

[Leo "costela" Antunes]

Hi

Firstly, this kind of question would be better suited in the
debian-mentors list.

Harshula wrote:
> Here's the example:
> 
> 1) a.tar.gz -> a.deb
> 2) b.tar.gz -> b.deb
> 3) c.tar.gz -> c.deb
> 

Are they really distributed in three separate upstream tarballs? If they
are, perhaps it would be better to generate a single tarball, if not,
there's no need to split it. A single tarball can - and most do -
generate many separate debs. Take a look at the New Maintainer Guide[0]
or get the sources of some existing packages to get the hang of it.

This should solve the manpage issue.


Cheers

[0] http://www.debian.org/doc/maint-guide/

-- 
Leo "costela" Antunes
[insert a witty retort here]



signature.asc
Description: OpenPGP digital signature

Re: QUESTION: Debian Policy: Manual pages

[Thibaut Paumard]

Le 14 févr. 08 à 17:04, Harshula a écrit :


Hi,

re: http://www.debian.org/doc/debian-policy/ch-docs.html#s12.1
---
Each program, utility, and function should have an associated manual
page included in the same package. [...]
---

Here's the example:

1) a.tar.gz -> a.deb
2) b.tar.gz -> b.deb
3) c.tar.gz -> c.deb

c.tar.gz contains only documentation, including man pages for
binaries/scripts in a.tar.gz and b.tar.gz.
[example of lintian warnings]
What is the recommended way to deal with this scenario?


My point-of-view is that it's fine IF the package which contains the  
binaries Depends: on the package which contains the manpage. In that  
case, you may write a lintian override.

(Note: IANADD... BADM)

Regards, Thibaut.