Package: undertaker
Version: 1.3b-1
Severity: wishlist
Tags: patch
The package descriptions for undertaker and undertaker-el feature
several English language errors; even with those fixed they could
do with a comprehensive rewrite to make them more comprehensible.
# Package: undertaker
[...]
# Description: static code analysis tool checking preprocessor directives
This is grammatical, but parsing it requires some effort. What it
means is that undertaker is a tool for analysis of static source code
which checks C preprocessor directives; but it could equally well be
parsed as saying that undertaker is a set of static directives for a
tool-checking preprocessor used in the analysis of secret codes.
I would recommend moving some of the complexity into the long
description.
# The undertaker is an preprocessor and configuration analyser. It can
^ ^
"Analyser" with an S is valid in en_GB but not en_US (my rewrite
avoids the issue); "an processor" is wrong either way.
"Preprocessor and configuration analyser" is a thoroughly baffling
description. It seems to be saying that undertaker is for analysing
preprocessors (like gpm and m4) and configurations (like, maybe,
symmetric versus asymmetric?)...
I would recommend replacing this line with something that specifically
mentions C preprocessor directives (since nothing else here says what
programming language you're talking about) and rehouses the phrase
"static (source) code analysis tool".
# check the structure of your preprocessor directives against different
~~~~
(Or indeed anybody else's preprocessor directives.)
# configuration models to find blocks than can't be selected or
^
Typo - you mean "that".
# deselected.
This is very unclear; it sounds as if it's talking about finding
blocks that can *neither* be selected *nor* deselected. Whatever that
means - those aren't even particularly standard terms for code being
activated or deactivated by preprocessor conditionals. (I can't find
anything much better, though.)
It seems to me that this explanation would be more intelligible if it
mentioned the terminology of "dead" and "undead" blocks, which is,
after all, the justification for the package's name.
# Package: undertaker-el
[...]
# Description: emacs integration for undertaker
^
What it integrates with is Emacs, the upstream "brand name" for the
software, rather than emacs, the (symlink to the) executable.
A side benefit of simplifying the short description for undertaker is
that it would make it possible to phrase this one as a minor variant.
I would also recommend including a small amount of shared
"boilerplate" text introducing undertaker in both long descriptions.
(This for a start makes life easier for translators.)
# undertaker-mode allows you to get the preprocessor condition under
This is a useless (though grammatical!) use of "allow", and an unclear
way of expressing what's going on. This software doesn't *permit* you
to *obtain* a particular piece of information; it just *displays* it.
# which the selected line of source code is built optionally incuding
^^^^^^^^ ^ ^
"The condition under which X happens" is an unnecessarily tortuous way
of phrasing this.
Wait, who selected this line of source code? Oh, was it me? Using
the word "selected" is probably a bad move when you just finished
talking about source code that can never be selected.
The words "built optionally" need to be separated by a comma. Come to
that, is "built" really the word you want? It's the output binary
that's built, not the source code (especially if this line's just a
comment). I don't want to use the word "selected", though! Maybe
"compiled" would work?
Typo: including.
# restrictions from a external configuration model
^ ^
"A external" is the reverse of the previous article error.
I'm not sure what this stuff about "including restrictions" is saying,
exactly (should "including" perhaps be "taking into account"?), but
I'll leave it as it is on the assumption that it would make more sense
if I carried on fighting my way through the documentation.
My suggested rewrite:
| Package: undertaker
[...]
| Description: preprocessor directive analysis tool
| The undertaker is a static source code analysis tool for checking C
| preprocessor directives.
| .
| It can check their structure against different configuration models to
| find "dead" blocks that can never be selected and "undead" blocks that
| can never be deselected.
|
| Package: undertaker-el
[...]
| Description: preprocessor directive analysis tool for Emacs
| The undertaker is a static source code analysis tool for checking C
| preprocessor directives.
| .
| This package provides an undertaker-mode for Emacs. Given a line of code
| under the cursor, it shows the preprocessor conditional that controls
| whether that code is compiled, optionally including restrictions from
| an external configuration model.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru undertaker-1.3b.pristine/debian/control undertaker-1.3b/debian/control
--- undertaker-1.3b.pristine/debian/control 2012-06-30 17:48:39.000000000 +0100
+++ undertaker-1.3b/debian/control 2012-12-17 02:32:52.638724110 +0000
@@ -23,16 +23,22 @@
Package: undertaker
Architecture: any
Depends: git, ${misc:Depends}, ${python:Depends}, ${shlibs:Depends}
-Description: static code analysis tool checking preprocessor directives
- The undertaker is an preprocessor and configuration analyser. It can
- check the structure of your preprocessor directives against different
- configuration models to find blocks than can't be selected or
- deselected.
+Description: preprocessor directive analysis tool
+ The undertaker is a static source code analysis tool for checking C
+ preprocessor directives.
+ .
+ It can check their structure against different configuration models to
+ find "dead" blocks that can never be selected and "undead" blocks that
+ can never be deselected.
Package: undertaker-el
Architecture: all
Depends: emacsen | emacs23, undertaker, ${misc:Depends}, ${shlibs:Depends}
-Description: emacs integration for undertaker
- undertaker-mode allows you to get the preprocessor condition under
- which the selected line of source code is built optionally incuding
- restrictions from a external configuration model
+Description: preprocessor directive analysis tool for Emacs
+ The undertaker is a static source code analysis tool for checking C
+ preprocessor directives.
+ .
+ This package provides an undertaker-mode for Emacs. Given a line of code
+ under the cursor, it shows the preprocessor conditional that controls
+ whether that code is compiled, optionally including restrictions from
+ an external configuration model.
