Re: Bug#688671: Please review package description boilerplate and line up short descriptions
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
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.
Reply to: