[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: RFH: Description, manpage and more?!

Kai Wasserbäch <debian@carbon-project.org> writes:

> [Please CC me, I'm not subscribed to the list.]


> I've a new package, skanlite, which is right now in the NEW queue [0].
> I'd be glad, if some of you could check the short and long description
> of the package,

Sure, I'll put my comments in this message.

> have a look at the manpage (maybe write a new one, this is more or
> less a very quick&dirty thing, just to silence lintian *g*)

Tools are not deities to be appeased
<URL:http://mid.gmane.org/20090502013433.GQ8633@ZenIV.linux.org.uk>. If
it were only the tool's happiness we cared about, that would be rather
foolish. If Lintian is emitting an error, it's because you need to do
something to please *people*.

In this case, you need to care enough about the people who use your
package to write (or motivate others to write) good, useful manpages for

For writing a manpage, you might prefer to write a reStructuredText
document and build the manpage using the ‘rst2man’ package. (Disclosure:
I maintain that package, and would very much like to receive feedback
From users via bug reports.)

On to the package description:

> Description: KDE4 image scanner based on the KSane backend

I think the version of KDE might be redundant in the description; the
user can trust that the dependencies will ensure the correct version of
KDE libraries, so perhaps this should only mention that it's for KDE.

Why is it important to the reader whether this is “based on the KSane
backend”? Does this help the reader decide whether to install the
package? Is there some more explicit way of saying what this means for
an install-or-not decision?

This leaves me with a synopsis of:

    image scanner for KDE

If there is some other compelling reason to choose this package over
other image scanner packages, that would be good in the synopsis.

>  Skanlite is a small and simple scanner application for KDE4 which allows easy
>  scanning of images with an attached scanner. Through the KSane backend it can
>  access a wide variety of different scanner models.

This is perfectly acceptable English.

Is there anything more that can be said for distinguishing this package
From other image scanner packages? “Small and simple” is rather
over-used in package descriptions, is there any more specific
description you can use instead?

>  .
>  Skanlite can be considered the replacement of Kooka.

In what way can it be considered the replacement? Is it a direct
successor, a fork, a re-write, or something else?

The .po file:

> # Copyright (C) YEAR This_file_is_part_of_KDE
> # This file is distributed under the same license as the PACKAGE package.

This needs to be completed truthfully with full copyright information
(use the copyright symbol ©, year of publication, legal name of entity
holding copyright); the boilerplate is useless.

There is inconsistent usage of sentence-ending full-stop (“.”)
characters. If these are all used in the same context, please choose one
style and stick with it consistently; I would recommend ending each
sentence with a full-stop to be a good default choice.

For example:

> #. i18n: file: settings.ui:11
> #. i18n: ectx: property (text), widget (QCheckBox, showB4Save)
> #: rc.cpp:6 rc.cpp:48
> msgid "Preview the image before saving."
> msgstr "Preview the image before saving."

is inconsistent with:

> #. i18n: file: settings.ui:26
> #. i18n: ectx: property (text), item, widget (QComboBox, saveModeCB)
> #: rc.cpp:12 rc.cpp:54
> msgid "Open the save dialog for every image"
> msgstr "Open the save dialogue for every image"

Either both (and all other sentences like them) should end with a
full-stop (“.”), or none should.

> #. i18n: file: settings.ui:44
> #. i18n: ectx: property (text), widget (QLabel, label)
> #: rc.cpp:21 rc.cpp:63
> msgid "Save Location:"
> msgstr "Save Location:"

Why is this using Title Case, when it seems to be merely a prompt and
not a title?

    msgid "Save location:"
    msgstr "Save location:"

> #. i18n: file: settings.ui:86
> #. i18n: ectx: property (text), widget (QLabel, label_2)
> #: rc.cpp:27 rc.cpp:69
> msgid "Name & Format:"
> msgstr "Name & Format:"

Unless space is extremely tight, I would recommend expanding the
ampersand “&” to the full word “and”:

    msgid "Name and Format:"
    msgstr "Name and Format:"

> #: rc.cpp:42
> msgid "Your emails"
> msgstr "andrew_coles@yahoo.co.uk"

Note that email is a system, and makes no sense in the plural. The thing
referred to in this message is an “email address”:

    #: rc.cpp:42
    msgid "Your email addresses"
    msgstr "andrew_coles@yahoo.co.uk"

 \       “The man who is denied the opportunity of taking decisions of |
  `\      importance begins to regard as important the decisions he is |
_o__)                        allowed to take.” —C. Northcote Parkinson |
Ben Finney

Attachment: pgpRz5OC4MHkD.pgp
Description: PGP signature

Reply to: