Re: Bug#654334: Please rewrite package description
Martin Eberhard Schauer wrote:
> to me the description of liboauth0 is quite useless as it does not say, what
> OAuth can do for me.
(Which is a Policy 3.4 "should", though libraries tend to get more
leeway than things that end-users need to find for themselves.)
> Description: C library for implementing OAuth 1.0
> liboauth is a collection of C functions implementing the
> OAuth Core 1.0 standard API.
> .
> This package contains the shared libraries
The one non-obvious fact I would learn from this description is what
API version it implements - but now that I've read Wikipedia enough to
know that there's a 2.0, I also want to know if "1.0" includes 1.0a!
(A grep through the sources suggests that the answer is yes.)
> liboauth-dev gives more information, but still does not explain what
> OAuth is about.
>
> Description: C library for implementing OAuth 1.0 (development files)
> liboauth is a collection of C functions implementing the
> OAuth Core 1.0 standard API. liboauth provides basic functions to escape
> and encode parameters according to OAuth specs and offers high-level
> functions to sign requests or verify signatures.
> .
> This package contains the development files.
(I'd nitpick some of the English here too...)
> It would be nice to have the boilerplate from ~-dev be available in liboauth
> as well. As I believe that libraries provide some functions in most cases I
> would like to suggest alternate package descriptions:
>
> Package: liboauth-dev
> Section: libdevel
> Architecture: any
> Depends: liboauth0 (= ${binary:Version}), libcurl4-nss-dev, ${misc:Depends}
> Description: C library implementing the OAuth 1.0 API (development files)
> liboauth provides basic functions to escape and encode parameters
> according to OAuth specs and offers high-level functions to sign
> requests or verify signatures.
>
> Package: liboauth0
> Architecture: any
> Pre-Depends: ${misc:Pre-Depends}
> Depends: ${misc:Depends}, ${shlibs:Depends}
> Multi-Arch: same
> Description: C library implementing the OAuth 1.0 API (runtime)
>
> Perhaps one could even copy and paste from RFC 5849 (1):
>
> The OAuth 1.0 Protocol
>
> Abstract
>
> OAuth provides a method for clients to access server resources on
> behalf of a resource owner (such as a different client or an end-
> user). It also provides a process for end-users to authorize third-
> party access to their server resources without sharing their
> credentials (typically, a username and password pair), using user-
> agent redirections.
This is a good readable summary, but still a bit wordy for our
purposes. The OAuth FAQ is terser:
# OAuth is an authentication protocol that allows users to approve
# application to act on their behalf without sharing their password.
It's odd, though - before I looked it up I could only remember two
facts about OAuth, and neither of them have been mentioned yet:
* it's short for "Open Authorization";
* it's used by apps such as Twitpic.
So here's a first attempt:
Description: Open Authorization 1.0 library - runtime
OAuth is an authentication protocol that allows users to approve a
client (such as a Twitter third-party app) to act on their behalf
without sharing their password. liboauth provides basic functions to
escape and encode parameters according to the OAuth Core 1.0a API, and
offers high-level functions to sign requests or verify signatures.
.
This package contains the shared libraries.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: