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

Steve Langasek vorlon at debian.org
Sat Aug 23 20:27:12 UTC 2008

On Sat, Aug 23, 2008 at 01:55:23PM +0100, Justin B Rye wrote:
> 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.

The devref recommendation is wrong.  DevRef is not policy, and the
grammatical justification given in 6.2.2 is bogus: it is *not* recommended
to use an appositive clause, the recommendation is to use an appositive
*phrase*, and the article is an integral part of the appositive phrase that
should not be omitted.

Bad (and just plain incorrect) recommendations should not be followed merely
because they've been adopted by the devref.

> * 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!

Again, the distinction between Unix and Linux is immaterial.  For all
intents and purposes, Linux is a "Unix system".

>  Likewise, "Windows, NT, OS/2 and DOS clients"... NT is also Windows,
> and Samba works for (smbclient on) OpenVMS too!

Yes, this needs fixing.

> * 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.

No, it wouldn't. ;)

> 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 version of samba currently in Lenny does /not/ have a Homepage: field,
nor any mention of this in the changelog.  Which version were you looking

I agree with fixing this; the Homepage field needs to be added at the same
time as the description is amended, then.  (None of this seems appropriate
for lenny, IMHO; there are much more serious issues for us to burn our karma

> * 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.

"the company's" =~ "yours".

Agreed wrt omitting the branding and kernel references.

> * 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.

I agree; I think this has persisted by virtue of momentum alone.

> * 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"...

Is "Network Neighborhood" still the current terminology?  It's been a while
since I've sat at a Windows machine, but I don't remember this being the
current term in XP.

I certainly don't like this being used as the short description, regardless.

Anyway, if we're going to seed with keywords, I have a few others in mind...

> 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.

 Description: SMB/CIFS file, print, and login server for Unix
  Samba is an implementation of the SMB/CIFS protocol for Unix systems,
  providing support for cross-platform file and printer sharing with
  Microsoft Windows, OS X, and other Unix systems.  Samba can also function
  as an NT4-style domain controller, and can integrate with both NT4 domains
  and Active Directory realms as a member server.
  This package provides the components necessary to use Samba as a
  stand-alone file and print server.  For use in an NT4 domain or Active
  Directory realm, you will also need the winbind package.
  This package is not required for connecting to existing SMB/CIFS servers
  (see smbclient) or for mounting remote filesystems (see smbfs).

Eliding the reference to documentation, which should be done using a
"Suggests:" relationship on the package, not in the description.

Steve Langasek                   Give me a lever long enough and a Free OS
Debian Developer                   to set it on, and I can move the world.
Ubuntu Developer                                    http://www.debian.org/
slangasek at ubuntu.com                                     vorlon at debian.org

More information about the Pkg-samba-maint mailing list