Bug#688671: Please review package description boilerplate and line up short descriptions

[Justin B Rye]

Martin Eberhard Schauer wrote:
> reviewing the translation of libhepmc-dev (1) I asked myself whether the wording
> (copied from upstream (2)) is correct.
> 
> I'm a German native and quite confident in my command of the English language.
> So the "event record" is my problem. Shouldn't it be an "event recorder"?

Yes, the user manual makes it clear that the "event record" is the
body of data maintained by this software, so really it ought to be
called an event recorder or something; maybe we can sidestep the
problem by talking about an "event record library"?

> Moreover, in the short descriptions there are too many capital letters and the
> short descriptions of libhepmcfio and libhepmcfio4-dev do not match the rest
> of the short descriptions. (3)

That is:

# Package: libhepmc4
[...]
# Description: Event Record for Monte Carlo Generators
#  The HepMC package is an object oriented event record written in C++ for
#  High Energy Physics Monte Carlo Generators.

Well, I see a motivation for capitalising "High Energy Physics" and
"Monte Carlo" (HEP MC), but not the rest.  Calling the suite of Debian
packages a "package" just adds to the confusion about where the event
record data fits into this.

  Description: Monte Carlo event record library
   HepMC is an object oriented C++ event record library for High Energy
   Physics Monte Carlo generators.

(This does make the synopses slightly less informative, but I see
other people on the net using similar phrases to describe HepMC.)

#  .
#  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
#  number of entries is unlimited, spin density matrices can be stored with
#  each vertex, flow patterns (such as color) can be stored and traced,
#  integers representing random number generator states can be stored, and an
#  arbitrary number of event weights can be included. Particles and vertices
#  are kept separate in a graph structure, physically similar to a physics
#  event.
#  .
#  The added information supports the modularisation of event generators.
#  Event information is accessed by means of iterators supplied with the
#  package. 

This is a bit long, but otherwise okay (and I wouldn't know how to
compress it anyway).  There should probably be a final "this package
provides the runtime library for HepMC".

# Package: libhepmc-dev
[...]
# Description: Event Record for Monte Carlo Generators - development files
[$BOILERPLATE]
#  .
#  This package provides development files of HepMC.

s/of/for/
 
# Package: libhepmcfio4
[...]
# Description: fio library of HepMC

I thought for a while it meant the fio that's a Debian package, but
there's no package dependency connection, so apparently it's some
other acronym.  I'm fairly sure that the "IO" still stands for
"Input/Output", but what's the "F" if not "Flexible"?  Maybe "File"?
"Fast"?  "Formatted"?  Since it's talking about inter-language
wrappers I'll guess it's "Fortran I/O".

MES has:       event record for Monte Carlo Generators, fio library

I'd suggest:   Monte Carlo event record FIO library

[$BOILERPLATE]
#  .
#  The fio library of HepMC provides wrappers of HEPEVT, Pythia and Herwig.

Assuming I've guessed right about what "fio" means:

   This package provides Fortran I/O wrappers for HEPEVT, Pythia, and Herwig.

# Package: libhepmcfio-dev
[...]
# Description: fio library of HepMC - development files

Or:            Monte Carlo event record FIO library - development files

[$BOILERPLATE]
#  .
#  This package provides development files of fio library of HepMC.

   This package provides development files for the HepMC Fortran I/O
   library.

# Package: hepmc-examples
[...]
# Description: Event Record for Monte Carlo Generators - example files
[$BOILERPLATE]
#  .
#  This package provides example source files of HepMC.

s/of/for/
 
# Package: hepmc-user-manual
[...]
# Description: Event Record for Monte Carlo Generators - User Manual

Unnecessary Capitalisation.

[$BOILERPLATE]
#  .
#  This package provides HepMC2 User Manual.

The extra "2" sounds like a hint that upstream are planning to bump
HepMC to version 3 but keep the version-2 manual as the only
documentation.  Assuming that's not the case:

   This package provides the user manual for HepMC.

# Package: hepmc-reference-manual
[...]
# Description: Event Record for Monte Carlo Generators - Reference Manual

Unnecessary Capitalisation.

[$BOILERPLATE]
#  .
#  This package provides HepMC2 Reference Manual.

   This package provides the reference manual for HepMC.

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package
-------------- next part --------------
diff -ru hepmc-2.06.09.pristine/debian/control hepmc-2.06.09/debian/control
--- hepmc-2.06.09.pristine/debian/control	2012-06-21 13:29:45.000000000 +0100
+++ hepmc-2.06.09/debian/control	2012-09-24 20:18:49.400411484 +0100
@@ -19,9 +19,9 @@
 Depends: ${shlibs:Depends}, ${misc:Depends}
 Recommends: libhepmcfio
 Suggests: libhepmc-dev, libhepmcfio-dev
-Description: Event Record for Monte Carlo Generators
- The HepMC package is an object oriented event record written in C++ for
- High Energy Physics Monte Carlo Generators.
+Description: Monte Carlo event record library
+ HepMC is an object oriented C++ event record library for High Energy
+ Physics Monte Carlo generators.
  .
  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
  number of entries is unlimited, spin density matrices can be stored with
@@ -34,6 +34,8 @@
  The added information supports the modularisation of event generators.
  Event information is accessed by means of iterators supplied with the
  package. 
+ .
+ This package provides the runtime library for HepMC.
 
 Package: libhepmc-dev
 Section: libdevel
@@ -41,9 +43,9 @@
 Depends: libhepmc4 (= ${binary:Version}), ${shlibs:Depends}, ${misc:Depends}
 Recommends: libhepmcfio-dev
 Suggests: hepmc-examples, hepmc-user-manual, hepmc-reference-manual
-Description: Event Record for Monte Carlo Generators - development files
- The HepMC package is an object oriented event record written in C++ for
- High Energy Physics Monte Carlo Generators.
+Description: Monte Carlo event record library - development files
+ HepMC is an object oriented C++ event record library for High Energy
+ Physics Monte Carlo generators.
  .
  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
  number of entries is unlimited, spin density matrices can be stored with
@@ -57,7 +59,7 @@
  Event information is accessed by means of iterators supplied with the
  package.
  .
- This package provides development files of HepMC.
+ This package provides development files for HepMC.
 
 Package: libhepmcfio4
 Section: libs
@@ -66,9 +68,9 @@
 Pre-Depends: ${misc:Pre-Depends}
 Depends: libhepmc4 (= ${binary:Version}), ${shlibs:Depends}, ${misc:Depends}
 Suggests: libhepmcfio-dev, libhepmc-dev
-Description: fio library of HepMC
- The HepMC package is an object oriented event record written in C++ for
- High Energy Physics Monte Carlo Generators.
+Description: Monte Carlo event record FIO library
+ HepMC is an object oriented C++ event record library for High Energy
+ Physics Monte Carlo generators.
  .
  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
  number of entries is unlimited, spin density matrices can be stored with
@@ -82,16 +84,16 @@
  Event information is accessed by means of iterators supplied with the
  package.
  .
- The fio library of HepMC provides wrappers of HEPEVT, Pythia and Herwig.
+ This package provides Fortran I/O wrappers for HEPEVT, Pythia, and Herwig.
 
 Package: libhepmcfio-dev
 Section: libdevel
 Architecture: any
 Depends: libhepmc-dev (= ${binary:Version}), libhepmcfio4 (= ${binary:Version}), ${shlibs:Depends}, ${misc:Depends}
 Suggests: hepmc-example, hepmc-user-manual, hepmc-reference-manual
-Description: fio library of HepMC - development files
- The HepMC package is an object oriented event record written in C++ for
- High Energy Physics Monte Carlo Generators.
+Description: Monte Carlo event record FIO library - development files
+ HepMC is an object oriented C++ event record library for High Energy
+ Physics Monte Carlo generators.
  .
  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
  number of entries is unlimited, spin density matrices can be stored with
@@ -105,16 +107,16 @@
  Event information is accessed by means of iterators supplied with the
  package.
  .
- This package provides development files of fio library of HepMC.
+ This package provides development files for the HepMC Fortran I/O library.
 
 Package: hepmc-examples
 Section: devel
 Architecture: all
 Depends: libclhep-dev, libpythia8-dev, libhepmc-dev (>= ${source:Version}), libhepmcfio-dev (>= ${source:Version}), ${misc:Depends}
 Suggests: hepmc-user-manual, hepmc-reference-manual
-Description: Event Record for Monte Carlo Generators - example files
- The HepMC package is an object oriented event record written in C++ for
- High Energy Physics Monte Carlo Generators.
+Description: Monte Carlo event record library - example files
+ HepMC is an object oriented C++ event record library for High Energy
+ Physics Monte Carlo generators.
  .
  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
  number of entries is unlimited, spin density matrices can be stored with
@@ -128,7 +130,7 @@
  Event information is accessed by means of iterators supplied with the
  package.
  .
- This package provides example source files of HepMC.
+ This package provides example source files for HepMC.
 
 Package: hepmc-user-manual
 Section: doc
@@ -136,9 +138,9 @@
 Depends: ${misc:Depends}
 Recommends: libhepmc-dev, libhepmcfio-dev
 Suggests: hepmc-reference-manual
-Description: Event Record for Monte Carlo Generators - User Manual
- The HepMC package is an object oriented event record written in C++ for
- High Energy Physics Monte Carlo Generators.
+Description: Monte Carlo event record library - user manual
+ HepMC is an object oriented C++ event record library for High Energy
+ Physics Monte Carlo generators.
  .
  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
  number of entries is unlimited, spin density matrices can be stored with
@@ -152,16 +154,16 @@
  Event information is accessed by means of iterators supplied with the
  package.
  .
- This package provides HepMC2 User Manual.
+ This package provides the user manual for HepMC.
 
 Package: hepmc-reference-manual
 Section: doc
 Architecture: all
 Depends: ${misc:Depends}
 Recommends: libhepmc-dev, libhepmcfio-dev, hepmc-user-manual
-Description: Event Record for Monte Carlo Generators - Reference Manual
- The HepMC package is an object oriented event record written in C++ for
- High Energy Physics Monte Carlo Generators.
+Description: Monte Carlo event record library - reference manual
+ HepMC is an object oriented C++ event record library for High Energy
+ Physics Monte Carlo generators.
  .
  Many extensions from HEPEVT, the Fortran HEP standard, are supported: the
  number of entries is unlimited, spin density matrices can be stored with
@@ -175,5 +177,4 @@
  Event information is accessed by means of iterators supplied with the
  package.
  .
- This package provides HepMC2 Reference Manual.
-
+ This package provides the reference manual for HepMC.