Re: Bug#697656: Please rewrite package description boilerplate
Martin Eberhard Schauer wrote:
> Dear Maintainers,
> the package descriptions of the *gupnp-av* packages (1) were a little bit hard
> to understand for me. My main concern is the boilerplate as used in (2):
[...]
For a library (which will be pulled in by dependencies when needed)
there's much less need for explanations; as long as there aren't any
outright errors, and gupnp-tools has something more end-user-oriented,
I wouldn't have worried about this one.
> Description: audio/video utility library for GUPnP
^^^^^^^^^^^
The capitalisation served as an "inline expansion" of the AV part of
GUPnP-AV; and "audio/video" is wrong - most dictionaries say AV means
"audiovisual". So I suppose I'm recommending "AudioVisual".
> GUPnP is an object-oriented open source framework for creating UPnP devices
> and control points, written in C using GObject and libsoup. The GUPnP API is
> intended to be easy to use, efficient and flexible.
d-l-e "house style" would put an extra comma after "efficient", but I
wouldn't bother changing it if we're not also changing gupnp-tools.
Mind you, how many APIs don't claim to be aiming at "easy to use,
efficient and flexible"?
> .
> GUPnP-AV is a collection of helpers for building audio/video applications
> using GUPnP.
You've lost the "providing DIDL parser/writer and search criteria
parser objects" part.
How about this as boilerplate:
GUPnP is an object-oriented open source framework for creating UPnP
devices and control points, written in C using GObject and libsoup. It
provides DIDL parser/writer and search criteria-parser objects.
Patch attached; but I somehow doubt it'll get an unblock for Wheezy.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru gupnp-av-0.10.3.pristine/debian/control gupnp-av-0.10.3/debian/control
--- gupnp-av-0.10.3.pristine/debian/control 2012-03-30 17:00:00.000000000 +0100
+++ gupnp-av-0.10.3/debian/control 2013-01-08 10:37:42.207057448 +0000
@@ -24,9 +24,12 @@
Section: libs
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
-Description: Audio/Visual utility library for GUPnP
- An audio/visual utility library for GUPnP, providing DIDL parser/writer and
- search criteria parser objects.
+Description: AudioVisual utility library for GUPnP
+ GUPnP is an object-oriented open source framework for creating UPnP
+ devices and control points, written in C using GObject and libsoup. It
+ provides DIDL parser/writer and search-criteria parser objects.
+ .
+ This package contains the shared library.
Package: gir1.2-gupnp-av-1.0
Section: introspection
@@ -34,12 +37,13 @@
Depends: ${misc:Depends}, ${gir:Depends}
Conflicts: gir1.0-gupnp-av-1.0
Replaces: gir1.0-gupnp-av-1.0
-Description: GObject introspection data for the GUPnP-AV library
- This package contains introspection data for GUPnP-AV, a UPnP-AV
- library.
+Description: AudioVisual utility library for GUPnP - introspection data
+ GUPnP is an object-oriented open source framework for creating UPnP
+ devices and control points, written in C using GObject and libsoup. It
+ provides DIDL parser/writer and search-criteria parser objects.
.
- It can be used by packages using the GIRepository format to generate
- dynamic bindings.
+ This package contains data in GObject Introspection Repository format
+ which can be used to generate dynamic bindings.
Homepage: http://live.gnome.org/GObjectIntrospection
Package: libgupnp-av-1.0-dev
@@ -48,9 +52,10 @@
Depends: libgupnp-av-1.0-2 (= ${binary:Version}), gir1.2-gupnp-av-1.0, libgupnp-1.0-dev (>= 0.10), ${misc:Depends}
Suggests: libgupnp-av-doc
Replaces: gir-repository-dev (<= 0.6.5-5)
-Description: Audio/Visual utility library for GUPnP (development files)
- An audio/visual utility library for GUPnP, providing DIDL parser/writer and
- search criteria parser objects.
+Description: AudioVisual utility library for GUPnP - development files
+ GUPnP is an object-oriented open source framework for creating UPnP
+ devices and control points, written in C using GObject and libsoup. It
+ provides DIDL parser/writer and search-criteria parser objects.
.
This package contains the development files.
@@ -60,9 +65,10 @@
Architecture: any
Depends: libgupnp-av-1.0-2 (= ${binary:Version}), ${misc:Depends}
Recommends: libgupnp-1.0-dbg
-Description: Audio/Visual utility library for GUPnP (debug symbols)
- An audio/visual utility library for GUPnP, providing DIDL parser/writer and
- search criteria parser objects.
+Description: AudioVisual utility library for GUPnP - debug symbols
+ GUPnP is an object-oriented open source framework for creating UPnP
+ devices and control points, written in C using GObject and libsoup. It
+ provides DIDL parser/writer and search-criteria parser objects.
.
This package contains the debug symbols.
@@ -71,8 +77,9 @@
Architecture: all
Depends: lynx | www-browser, ${misc:Depends}
Recommends: libgupnp-doc
-Description: Audio/Visual utility library for GUPnP (documentation)
- An audio/visual utility library for GUPnP, providing DIDL parser/writer and
- search criteria parser objects.
+Description: AudioVisual utility library for GUPnP - documentation
+ GUPnP is an object-oriented open source framework for creating UPnP
+ devices and control points, written in C using GObject and libsoup. It
+ provides DIDL parser/writer and search-criteria parser objects.
.
This package contains the documentation.
Reply to: