Re: help to improve the description of remotetea package

[Justin B Rye <jbr@edlug.org.uk>]

Picca Frédéric-Emmanuel wrote:
> MY mentors told me to send an email to your list to improve the
> description of my package.

(Apologies if the CC is unwelcome)

> Package: remotetea

Shouldn't it be called something like "libremotetea1-java"?

http://www.debian.org/doc/packaging-manuals/java-policy/x105.html

> Description: ONC/RPC for Java package

Is it the one and only implementation of Sun TLA/TLA for Java?
If it has rivals, you should mention the features that make it
special - it might also be helpful to explain why its developers
chose to call it "RemoteTea" instead of something obvious like
"SunRPC"! 

Oh, and you don't need to say it's a package.

>  This package implements Sun's ONC/RPC Remote Procedure Call
> specification (see RFC 1831, RFC 1832, RFC 1833).
>  .
>  Functionality currently supported:
>   - RPC calls over TCP/IP as well as UDP/IP.
>   - RPC client functionality.
>   - RPC server functionality org.acplt.oncrpc.server
>   - Querying the ONC/RPC potmapper
>   - jrpcgen-utility for converting x-files into Java classes.
>   - Support for authentication types AUTH_NONE, AUTH_UNIX and AUTH_SHORT
>   on both the client and server side.
> 
> 
> it seems that the description is to cryptic.
> 
> http://lists.debian.org/debian-mentors/2009/08/msg00031.html

It's pretty good English (though we're standardising on asterisks
these days), and it doesn't need to be a complete beginners' guide
to SunRPC; people who don't know they need it probably won't need to
know about it.  But it wouldn't hurt to have a few extra words.

Minor changes:
 • I've left out some repetitions of "functionality" and "RPC";
 • I've dropped "org.acplt.oncrpc.server" because I don't see how it
	fits in;
 • it's poRtmapper;
 • I've moved the jrpcgen part because it's not really "supported
	ONC/RPC functionality", it's a utility for Java developers.

Suspiciously, a google search for "AUTH_NONE AUTH_UNIX AUTH_SHORT"
finds a page of Remote Tea documentation as its top hit.  Do other
people ever refer to them in these terms, or should it be translated
into something less technical?

Here's my attempt:

  Description: Sun ONC/RPC support for Java
   This package implements Sun's Open Network Computing Remote Procedure
   Call specification (see RFC 1831, RFC 1832, RFC 1833) in pure Java.
   .
   It supports:
    * RPC calls over TCP/IP as well as UDP/IP;
    * both client and server functionality;
    * portmapper querying;
    * authentication types AUTH_NONE, AUTH_UNIX, and AUTH_SHORT
      (on both client and server sides).
   .
   The utility jrpcgen is provided to compile .x files into Java classes.

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package