[Pkg-gnupg-maint] Bug#575763: gnupg: simplification of README

[Jonathan Nieder]

Package: gnupg
Version: 1.4.10-3
Severity: wishlist

I was looking over the documentation in /usr/share/doc/gnupg to learn to
carry out some simple task.

Unfortunately, the current README’s noise-to-signal is very low for a Debian
package without a README.Debian.  I am reminded of W. Borgert’s call to
remove such files altogether five years ago [1].

It is not as bad as to call for that that: the only irrelevant sections are
“Installation”, “How to Verify the Source” (makes sense for a README.source,
though), “Configure options”, “Installation Problems”, “Specific problems on
some machines”, “Creating an RPM package”, and “Building Universal Binaries
on Apple OS X”.  This could be mostly fixed if upstream wants by renaming
INSTALL to INSTALL.generic and splitting off a new INSTALL file.

Here is a potential README.Debian with relevant information about how
gnupg integrates with Debian.  I do not imagine this is suitable in its
current form; feedback would be welcome!

-- %< --
GnuPG for Debian
================

A comprehensive manual (the GNU Privacy Handbook) is included in the
gnupg-doc package.  It can also be found online at
<http://www.gnupg.org/documentation/guides.html>.

Smart card readers
------------------
If udev, consolekit, and gnupg are installed, then locally logged-in
users will be automatically granted permission to access any detected
USB SmartCard reader devices.

/lib/udev/rules.d/60-gnupg.rules lists the supported devices.  If yours
is not listed there, you can try creating a copy of that file in
/etc/udev/rules.d/ with your device’s information.  Wishlist bugs
against the gnupg package about unsupported devices would be welcome.

Differences from upstream GnuPG 1.4.10
--------------------------------------
Fixes from the upstream 1.4 branch (thus intended for 1.4.11):

 - r5222: config.links: Remove asm modules for all sparc64.  This fixes
   an FTBFS failure on sparc64, as it tries to use SPARC32 assembly code
   on SPARC64.
 - r5229: tdbio.c (tdbio_set_dbname): Do not call log_fatal after creating
   the directory.  Fixes bug#1169.
 - r5236: Fix bug#1059 (missing status line signature verification done with
   a subkey while on the main key has expired).
 - r5253: gnupg1.texi: Fix dir entry.  Fixes bug#1183
 - r5255: Teach gnupg to show a less ambiguous prompt than "Command>".
 - r5257: doc/faq.raw: Fix bug reporting address.
 - r5264: keygen.c (ask_user_id): Avoid infinite loop in case of invalid
   data.  Fixes bug#1186.

Fixes back-ported from the upstream 2.0 branch:

 - r5259: doc/gpg.texi, doc/faw.raw: Minor changes.

Fixes not yet applied upstream:

 - bug#1172: gpg.texi: document the --edit-key primary uid display format

The bug numbers in this section refer to the upstream bug tracker at
<https://bugs.g10code.com/gnupg/>.
-- >% --

Thoughts?
Jonathan

[1] http://lists.debian.org/debian-devel/2005/08/msg00705.html