Package: python-docopt
Version: 0.6.1-1
Severity: wishlist
Tags: patch
You asked for reviews of your other package descriptions, so here's
one...
> Package: python-docopt
[...]
> Description: Creates beautiful command-line interfaces
This is a capitalised verb-phrase; upstream use a blurb "command-line
interface description language" which happens to be a DevRef-compliant
uncapitalised noun-phrase describing the software, so let's steal that
instead.
> docopt helps you:
> .
> * define interface for your command-line app, and
> * automatically generate parser for it.
^
Here's the part that persuaded me to bother making this a bug report.
This isn't the required formatting to make it work as a bulletted list
on (e.g.) http://packages.debian.org/sid/python-docopt - the asterisks
should be indented one space. But a list of two items is rarely worth
the effort, and the sentence just runs through it uninterrupted.
(You need a couple of extra articles, though.)
> .
> docopt is based on conventions that are used for decades in help messages and
I'm not sure this needs a new paragraph, and starting two
sentences in a row with "docopt" seems slightly repetitive. This
second one could just say "It is based..."
Then there's a tense problem: say "conventions that have been used for
decades" (or less longwindedly, "conventions used for decades").
> man pages for program interface description. Interface description in docopt
When I first read this I thought it was trying to say "used (a) in
help pages and (b) in man-pages-for-program-interface-descriptions",
but on second thoughts it must be "used (in help messages and in man
pages) for program interface descriptions".
> is such a help message, but formalized.
This final sentence is also hard to follow (not helped by the
continuing article drought), but if it's saying "the interface
descriptions produced by docopt are a formalised version of these help
messages" then there's not much new information here, and what there
is could easily be fitted into the previous sentence.
I would suggest:
Description: command-line interface description language
docopt helps you define an interface for your command-line app and
automatically generate a parser for it. Its interface descriptions are
based on a formalization of the standard conventions used in help
messages and man pages.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
diff -ru docopt-0.6.1.pristine/debian/control docopt-0.6.1/debian/control
--- docopt-0.6.1.pristine/debian/control 2013-09-14 21:28:23.000000000 +0100
+++ docopt-0.6.1/debian/control 2013-10-07 16:50:18.445617964 +0100
@@ -16,27 +16,19 @@
Package: python-docopt
Architecture: all
Depends: ${python:Depends}, ${misc:Depends}
-Description: Creates beautiful command-line interfaces
- docopt helps you:
- .
- * define interface for your command-line app, and
- * automatically generate parser for it.
- .
- docopt is based on conventions that are used for decades in help messages and
- man pages for program interface description. Interface description in docopt
- is such a help message, but formalized.
+Description: command-line interface description language
+ docopt helps you define the interface for your command-line app, and
+ automatically generate a parser for it. Its interface descriptions are
+ based on a formalization of the standard conventions used in help
+ messages and man pages.
Package: python3-docopt
Architecture: all
Depends: ${python3:Depends}, ${misc:Depends}
-Description: Creates beautiful command-line interfaces (Python3)
- docopt helps you:
- .
- * define interface for your command-line app, and
- * automatically generate parser for it.
- .
- docopt is based on conventions that are used for decades in help messages and
- man pages for program interface description. Interface description in docopt
- is such a help message, but formalized.
+Description: command-line interface description language (Python3)
+ docopt helps you define the interface for your command-line app, and
+ automatically generate a parser for it. Its interface descriptions are
+ based on a formalization of the standard conventions used in help
+ messages and man pages.
.
This is the Python 3 compatible version of the package.
