[Pkg-samba-maint] Bug#496200: samba: package description overhaul

[Justin B Rye]

Package: samba
Version: 2:3.2.1-1
Severity: minor

This is part of a set of related bugreports on the packages in the
Samba suite; I've already reported many of these issues (with some
suggested fixes) as a single bugreport on samba4 (see #486370), but
since that approach is a dud I'm trying the alternative of splitting
them up and targetting individual packages.

Current package description:         
# Description: a LanManager-like file and printer server for Unix
#  The Samba software suite is a collection of programs that
#  implements the SMB/CIFS protocol for unix systems, allowing you to serve
#  files and printers to Windows, NT, OS/2 and DOS clients. This protocol
#  is sometimes also referred to as the LanManager or NetBIOS protocol.
#  .
#  This package contains all the components necessary to turn your
#  Debian GNU/Linux box into a powerful file and printer server.
#  .
#  Currently, the Samba Debian packages consist of the following:
#  .
#   samba - LanManager-like file and printer server for Unix.
#   samba-common - Samba common files used by both the server and the client.
#   smbclient - LanManager-like simple client for Unix.
#   swat - Samba Web Administration Tool
#   samba-doc - Samba documentation.
#   samba-doc-pdf - Samba documentation in PDF format.
#   smbfs - Mount and umount commands for the smbfs (kernels 2.2.x and above).
#   libpam-smbpass - pluggable authentication module for SMB/CIFS password
#                    database
#   libsmbclient - Shared library that allows applications to talk to SMB/CIFS
#                  servers
#   libsmbclient-dev - libsmbclient shared libraries
#   libwbclient0 - Shared library for interfacing with the winbind service
#   winbind - Service to resolve user and group information from Windows NT
#             servers
#  .
#  It is possible to install a subset of these packages depending on
#  your particular needs. For example, to access other SMB/CIFS servers you
#  should only need the smbclient and samba-common packages.
#  .         
#  http://www.samba.org/         

Problems shared with other packages in the set:
* Developers Reference 6.2.2 says the package synopsis should not
	begin with an article.
* Samba is all about OS interoperability, so keep the OS names
	straight.  It's not just "for Unix" (or "unix systems"),
	it's also for GNU/Linux!  Likewise, "Windows, NT, OS/2 and
	DOS clients"... NT is also Windows, and Samba works for
	(smbclient on) OpenVMS too!
* the SMB/CIFS protocol is _not_ also referred to as "the LanManager
	or NetBIOS protocol" except by people copying this text.
	The comparison to LanManager in the synopsis line is
	particularly unhelpful and dated (and wasn't the correct
	spelling "LAN Manager"?)
* and a wishlist item: WIBNI all the packages in the suite had
	consistently styled short descriptions.

Problems unique to this package:
* the samba.org URL should be a policy-5.6.23-compliant Homepage:
	field on the source package.  In fact it already was, in the
	version of samba currently in Lenny, but 2:3.2.1-1 puts it
	back in the text.  Did something get reverted accidentally?
* the system the reader is considering installing samba onto is not
	necessarily "your Debian GNU/Linux box".  It may be "the
	company's Debian GNU/kFreeBSD virtual server".  Actually,
	mentioning Debian here is pointlessly Ubuntu-unfriendly.
* listing the members of the suite isn't very useful.  I'm sending
	separate reports asking for most of their short descriptions
	to be changed, but note that some of them here are already
	misquotes!  And repeating samba's short description in its
	own long description is ridiculous.
* the package samba does _not_ contain all the components necessary
	for running Samba.  That's why it depends on samba-common!
	But no need to advertise packages like samba-common here; if
	they're needed, they'll be pulled in automatically.
* the fact you can install some packages without having to install
	others is more of a basic property of the package management
	system than a samba feature worth mentioning here.
* and a wishlist item: WIBNI this package description had as many as
	possible of the keywords that users are going to search for
	if they don't happen to remember the word "Samba".  Search
	terms like "cross-platform", "interoperable with Windows
	network shares", "Network Neighborhood"...

Suggested replacement text:
| Description: Samba 'Network Neighborhood' server
|  The Samba software suite implements the SMB/CIFS protocol, providing
|  cross-platform support for Windows-style network shares.
|  .
|  This package sets a machine up as a powerful file and printer server
|  accessible from Microsoft operating systems. It is not required for
|  connecting to existing Samba servers (see smbclient) or for mounting Samba
|  file systems (see smbfs).
|  .
|  Documentation is supplied in the packages samba-doc and samba-doc-pdf.

-- 
JBR - please CC me (or the debian-l10n-english list) in replies