Package: apf-server
Version: 0.8.4
Severity: wishlist
Tags: patch
Dear Maintainer,
The content of the package descriptions for apf-{server,client} is
great, but there are several problems with the English.
> Package: apf-server
(Not to be confused with the APF available as apf-firewall!)
[...]
> Description: Server for Active Port Forwarding
^ ^ ^ ^
The DevRef guidelines say there's no need to capitalise the first word
of a synopsis (it isn't a sentence), and then since "Active Port
Forwarding" isn't the expansion of APF there's no excuse for uppercase
there either.
> Active Port Forwarder is a tool for secure port forwarding. It uses ssl
^^^
The protocol is "SSL", not "ssl".
While I'm editing this bit I've turned the second sentence into a
subclause of the first just because I think it reads better.
> to increase security of communication between the server and the client.
I'd rejig the articles to make it more idiomatic (oh, and it also now
matches the upstream home page):
Active Port Forwarder is a tool for secure port forwarding, using SSL to
increase the security of communication between a server and a client.
> It is designed for people without an external IP who want to make some
Pedantically, s/IP/IP address/
> services available on the Internet. The Active Port Forwarder server
> (afserver) is placed on the machine with a public address, and the client
> (afclient) is placed on the machine behind a firewall or masquerade. This
> makes the second machine visible to the Internet.
(I considered splitting out some of this information about afserver
and afclient into the package-specific section below, but for now I
haven't bothered.)
> .
> This package provides the Active Port Forwarder server.
Having the first and third paragraphs as boilerplate with the
package-specific part in between doesn't make much sense. I've moved
this line to the end.
> .
> Short list of features:
> * Using one permanent data/control channel with flow control/packet
> buffering provides good performance and reasonably small latency.
"Small latency" is unidiomatic - say "low latency". But meanwhile
I'll impose the debian-l10n-english "house style" for these
bulletpoints, with semicolons instead of periods, no capitalisation,
and grammatically parallel items (standardising on verb phrases):
* uses one permanent data/control channel with flow control/packet
buffering to provide good performance and reasonably low latency;
> * Use zlib to compress the transferred data.
uses ;
> * Able to use ssl for all comunication or only for the autentification.
SSL ^ ^^^^^^ ;
Make that:
* can use SSL for all communications or for authentication only;
> * Able to transfer multiple tunnels in the one afclient <-> afserver
> connection making possible create more sophisticated tunneling scheme.
You don't "transfer" a tunnel - you set up a tunnel to allow data to
be transferred. There's no need for the ASCII-art "<->", either, and
"making possible create [...] scheme" is pidgin-English. I suggest:
* can set up multiple tunnels in the one afclient/afserver connection,
allowing sophisticated tunneling schemes;
> * Doesn't require root priviledges.
d privileges;
("Priviledge" is such a common typo I'm surprised Lintian doesn't
catch it.)
> * Doesn't use threads or other processes.
Processes other than threads? Well, clearly it does use processes,
and it's at least single-threaded, so it must mean something like:
* doesn't use multiple processes or threads.
> * The afclient can use external modules for user's packets filtering.
When you pile up attributive nouns in a heap like this they generally
don't need to be inflected: say "user packet filtering". Except...
hang on, the docs say it has modules to handle both "user's packets
filtering" and "service's packets filtering" (sic), which surely adds
up in summary to plain "packet filtering"?
But anyway, this bulletpoint doesn't belong here: facts specific to
the client belong in the description for apf-client, not in the
generic section.
> Package: apf-client
[...]
> Description: Client for Active Port Forwarding
Again, devref-compliant s/C/c/ and naming tweak.
The same boilerplate issues, then:
> This package provides the Active Port Forwarder client.
This line again belongs at the end, and needs to merge in the
client-specific item removed from the list.
This package provides the Active Port Forwarder client (which can also
use external modules for packet filtering).
(Do I understand that these are "external" in the sense of "you'll
need to write and compile them yourself"? If so, that should really
be stated more clearly.)
--
JBR
Ankh kak! (Ancient Egyptian blessing)
diff -ru apf-0.8.4.pristine/debian/control apf-0.8.4/debian/control
--- apf-0.8.4.pristine/debian/control 2012-06-25 12:04:21.000000000 +0100
+++ apf-0.8.4/debian/control 2012-06-25 15:47:02.091392511 +0100
@@ -9,49 +9,48 @@
Package: apf-server
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: Server for Active Port Forwarding
- Active Port Forwarder is a tool for secure port forwarding. It uses ssl
- to increase security of communication between the server and the client.
- It is designed for people without an external IP who want to make some
- services available on the Internet. The Active Port Forwarder server
+Description: server for active port forwarding
+ Active Port Forwarder is a tool for secure port forwarding, using SSL to
+ increase the security of communication between a server and a client. It
+ is designed for people without an external IP address who want to make
+ some services available on the Internet. The Active Port Forwarder server
(afserver) is placed on the machine with a public address, and the client
(afclient) is placed on the machine behind a firewall or masquerade. This
makes the second machine visible to the Internet.
.
- This package provides the Active Port Forwarder server.
- .
Short list of features:
- * Using one permanent data/control channel with flow control/packet
- buffering provides good performance and reasonably small latency.
- * Use zlib to compress the transferred data.
- * Able to use ssl for all comunication or only for the autentification.
- * Able to transfer multiple tunnels in the one afclient <-> afserver
- connection making possible create more sophisticated tunneling scheme.
- * Doesn't require root priviledges.
- * Doesn't use threads or other processes.
- * The afclient can use external modules for user's packets filtering.
+ * uses one permanent data/control channel with flow control/packet
+ buffering to provide good performance and reasonably low latency;
+ * uses zlib to compress the transferred data;
+ * can use SSL for all communications or for authentication only;
+ * can set up multiple tunnels in the one afclient/afserver connection,
+ allowing sophisticated tunneling schemes;
+ * doesn't require root privileges;
+ * doesn't use multiple processes or threads.
+ .
+ This package provides the Active Port Forwarder server.
Package: apf-client
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: Client for Active Port Forwarding
- Active Port Forwarder is a tool for secure port forwarding. It uses ssl
- to increase security of communication between the server and the client.
- It is designed for people without an external IP who want to make some
- services available on the Internet. The Active Port Forwarder server
+Description: client for active port forwarding
+ Active Port Forwarder is a tool for secure port forwarding, using SSL to
+ increase the security of communication between a server and a client. It
+ is designed for people without an external IP address who want to make
+ some services available on the Internet. The Active Port Forwarder server
(afserver) is placed on the machine with a public address, and the client
(afclient) is placed on the machine behind a firewall or masquerade. This
makes the second machine visible to the Internet.
.
- This package provides the Active Port Forwarder client.
- .
Short list of features:
- * Using one permanent data/control channel with flow control/packet
- buffering provides good performance and reasonably small latency.
- * Use zlib to compress the transferred data.
- * Able to use ssl for all comunication or only for the autentification.
- * Able to transfer multiple tunnels in the one afclient <-> afserver
- connection making possible create more sophisticated tunneling scheme.
- * Doesn't require root priviledges.
- * Doesn't use threads or other processes.
- * The afclient can use external modules for user's packets filtering.
+ * uses one permanent data/control channel with flow control/packet
+ buffering to provide good performance and reasonably low latency;
+ * uses zlib to compress the transferred data;
+ * can use SSL for all communications or for authentication only;
+ * can set up multiple tunnels in the one afclient/afserver connection,
+ allowing sophisticated tunneling schemes;
+ * doesn't require root privileges;
+ * doesn't use multiple processes or threads.
+ .
+ This package provides the Active Port Forwarder client (which can also
+ use external modules for packet filtering).
