Bug#710532: rfc5766-turn-server: broken synopsis

[Justin B Rye]

Package: rfc5766-turn-server
Version: 1.8.4.2-1
Severity: normal
Tags: patch

The package synopsis is broken between the short description line and
the long description (in a manner specifically forbidden in Debian
Policy 3.4.2, so I'm treating this as worse than my usual "Severity:
wishlist").  Even with that fixed it's hard to work out what it's
trying to say.

# Description: server for ICE/STUN/TURN, NAT traversal for VoIP and
#  WebRTC. [...]

Synopsis problem one: the word "WebRTC" has fallen off the end.

Synopsis problem two: is the package claiming to be
 1) a server (for ICE, or STUN, or TURN), and
 2) a NAT traversal for VOIP and WebRTC?
Or is it maybe claiming to be a server for
 1) ICE, a.k.a. STUN, a.k.a. TURN,
 2) NAT traversal for VoIP, and
 3) WebRTC?
Or maybe... various other valid parsings.

Synopsis problem three: ICE is the cover-term for the framework that
can make use of STUN and/or TURN, so it makes no particular sense to
talk about "ICE/STUN/TURN".  In fact I would recommend just not
mentioning ICE at all; for anybody who recognises the terms STUN and
TURN it's pretty much completely redundant, and for anybody who
doesn't it's an extra unexplained acronym.

It seems to me you'd be better off with something like:

  Description: NAT traversal server using STUN/TURN

(Or if you really insist on the ICE it could be something like
  Description: NAT traversal ICE server using STUN/TURN
but that's not in my patch.)

#          Free open source implementation of TURN Server / STUN Server /
#  Network Traffic Gateway

More problems.
 * This should be an introductory sentence, not a sentence fragment.
 * It's all very well for the upstream homepage to drone on and on
	about how this is a free open source implementation of
	something or other, but Debian packages can take all that for
	granted.
 * On the other hand this is where the expansions of STUN and TURN
	would fit nicely.
 * There's no particular reason for all this capitalisation; and
	"Network Traffic Gateway" doesn't even exist as jargon -
	Google says the homepage for this software is the only place
	using the expression.
 * The constant use of slashes to mean nothing in particular isn't
	helping either.
 * Missing period.

#                          The TURN Server is a VoIP media traffic NAT
#  traversal server and gateway. It can be used as a general-purpose
#  network traffic TURN server/gateway, too.
#  [...]

>From here on it settles down a bit, but there are still one or two
relatively trivial issues (such as missing or surplus articles) that
I'll fix while I'm patching the description.

My revised description, in full:

| Description: NAT traversal server using STUN/TURN
|  STUN (Session Traversal Utilities for NAT) and TURN (Traversal Using Relays
|  around NAT) are protocols that can be used to provide NAT traversal for VoIP
|  and WebRTC. This package provides a VoIP media traffic NAT traversal server
|  and gateway which can be used as a general-purpose network traffic TURN
|  server/gateway, too.
|  .
|  This implementation also includes some extra features.
|  . 
|  Supported RFCs:
|  TURN specs:
|   * RFC 5766 - base TURN specs;
|   * RFC 6062 - TCP relaying TURN extension;
|   * RFC 6156 - IPv6 extension for TURN;
|   * Experimental DTLS support as client protocol.
|  STUN specs:
|   * RFC 5389 - base "new" STUN specs;
|   * RFC 5769 - test vectors for STUN protocol testing;
|   * RFC 5780 - NAT behavior discovery support.
|  .
|  The implementation fully supports UDP, TCP, TLS, and DTLS as protocols between
|  the TURN client and the TURN server. Both UDP and TCP relaying are supported.
|  .
|  Flat files, MySQL, PostgreSQL, or Redis are all supported for the user
|  repository (if authentication is required).
|  Both short-term and long-term credentials mechanisms are supported.
|  For WebRTC applications, the TURN server REST API for time-limited
|  secret-based authentication is implemented.
|  .
|  Load balancing can be implemented either by external networking tools, or by
|  the built-in ALTERNATE-SERVER mechanism.
|  .
|  The implementation is intended to be simple to install and configure.
|  The project focuses on performance, scalability, and simplicity. 
|  The aim is to provide an enterprise-grade TURN solution.

-- System Information:
Debian Release: jessie/sid
  APT prefers testing
  APT policy: (990, 'testing'), (50, 'unstable')
Architecture: i386 (i686)

Kernel: Linux 3.8-2-686-pae (SMP w/1 CPU core)
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages rfc5766-turn-server depends on:
ii  adduser                  3.113+nmu3
ii  libc6                    2.17-3
ii  libevent-2.0-5           2.0.21-stable-1
ii  libevent-openssl-2.0-5   2.0.21-stable-1
ii  libevent-pthreads-2.0-5  2.0.21-stable-1
ii  libhiredis0.10           0.10.1-7
ii  libmysqlclient18         5.5.31+dfsg-1
ii  libpq5                   9.1.9-1
ii  libssl1.0.0              1.0.1e-2

rfc5766-turn-server recommends no packages.

rfc5766-turn-server suggests no packages.

-- no debconf information

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
-------------- next part --------------
A non-text attachment was scrubbed...
Name: pd.diff
Type: text/x-diff
Size: 3323 bytes
Desc: not available
URL: <http://lists.alioth.debian.org/pipermail/pkg-voip-maintainers/attachments/20130531/20ab22ff/attachment.diff>