Re: [#612195] make: improving the package description (again)
It is now two years since this bug was closed, but the fix shows no
sign of moving in the direction of Sid. Make, a package with a
six-figure popcon rating, still has a package description littered
with typos and awkward turns of phrase.
I provided a patch for this in February 2011 - indeed, I provided a
patch that would have dealt with the typos back in December 2008 as
part of bug #508456. If there is something wrong with my suggestions,
you only have to tell me and I'll happily do a rewrite.
Here's a re-review of the current description:
# Description: An utility for Directing compilation.
^^ ^ ^
Mispunctuated, and it's "a utility" (but there shouldn't be an article
there anyway).
# GNU Make is an utility which controls the generation of executables and
^
Again "a utility".
# other target files of a program from the program's source files. It
^^^^^^^^^^^^^^^^^^^^^^^^^
I've never been really happy about this use of the jargon term
"target", and I've finally worked out why. When you contrast "a
program" with "the program's source files", it's natural to read that
as drawing a binary versus sourcecode distinction; but the libraries
and so on generated by a build process aren't "target files of" the
compiled executable, they're targets of make!
The way we're *meant* to interpret it is that when it talks about the
target files "of a program" it means "of an upstream software
project's build system". But if you don't already understand what
it's trying to say (and especially if you don't already know what a
"target" is in this context), that can be unnecessarily hard to
decipher.
# determines automatically which pieces of a large program need to be
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^
It would be very slightly more idiomatic to say "automatically
determines" (though I probably wouldn't bother mentioning it if I
hadn't had to re-read this text so many times.)
Also, this insistent repetition of the word "program" is strange. Why
leave out libraries and so on? Just say "a large software project".
# (re)created, and issues the commands to (re)create them. Make is not
# limited to programs and executable, it can be applied to any task
^^^
Singular "executable" makes no sense, and this is a "comma splice"
(fixable with a simple s/,/;/).
# where a set of target files must be created based on a set of input
# files, based on dependency and processing rules. Indeed, Make is a
^^^^^^^^
"X based on Y based on Z" is awkward.
# general purpose dependency solver.
^
Another really pedantic one: the compound modifier "general-purpose"
should be hyphenated.
The version in experimental fixes the serious language errors, but as
usual it has a couple of new minor issues:
# Description: utility for directing compilation
# GNU Make is a utility which controls the generation of executables
# and other target files of a program from the program's source
# files. It determines automatically which pieces of a large program
# need to be (re)created, and issues the commands to (re)create
# them. Make can be used to organize any task in which targets (files)
^^^^^^^
# are to be automatically updated based on input files whenever the
# corresponding input is newer --- it is not limited to building
^^^^^
# computer programs. Indeed, Make is a general purpose dependency
# solver.
"Targets (files)" is an odd way to put it. What is the word in
parentheses doing there? Is it short for "targets (by which I mean
files)", or what? I can't see any interpretation that wouldn't be
improved by simply removing the word. For a start, targets don't need
to be files - they can be phony.
Also, a spaced triple dash is way over the top in anything that's
intended to be read by human beings rather than by TeX. If you really
want a Unicode em-dash, there would be nothing to stop you using a
real one, but standard practice in package descriptions is to stick to
plain 7-bit hyphen-minus. After all, "apt-cache search make" gives
output with at least one spaced hyphen-minus on every line...
So here's the version in my revised patch for 2013:
Description: utility for directing compilation
GNU Make is a utility which controls the generation of executables,
libraries, and other required files from a program's source files. It
automatically determines which pieces of a large software project need to
be (re)created, and issues the commands to (re)create them. Make can be
used to organize any task in which targets are to be automatically
updated based on input files whenever the corresponding input is newer -
it is not limited to building computer programs. Indeed, Make is a
general-purpose dependency solver.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru make-dfsg-3.81.pristine/debian/control make-dfsg-3.81/debian/control
--- make-dfsg-3.81.pristine/debian/control 2013-07-17 20:22:23.000000000 +0100
+++ make-dfsg-3.81/debian/control 2013-07-17 21:33:37.209080280 +0100
@@ -13,13 +13,13 @@
Priority: standard
Suggests: make-doc
Architecture: any
-Description: An utility for Directing compilation.
- GNU Make is an utility which controls the generation of executables and
- other target files of a program from the program's source files. It
- determines automatically which pieces of a large program need to be
- (re)created, and issues the commands to (re)create them. Make is not
- limited to programs and executable, it can be applied to any task
- where a set of target files must be created based on a set of input
- files, based on dependency and processing rules. Indeed, Make is a
- general purpose dependency solver.
+Description: utility for directing compilation
+ GNU Make is a utility which controls the generation of executables,
+ libraries, and other required files from a program's source files. It
+ automatically determines which pieces of a large software project need to
+ be (re)created, and issues the commands to (re)create them. Make can be
+ used to organize any task in which targets are to be automatically
+ updated based on input files whenever the corresponding input is newer -
+ it is not limited to building computer programs. Indeed, Make is a
+ general-purpose dependency solver.
Depends: ${shlibs:Depends}
Reply to: