Am Donnerstag, den 20.11.2008, 14:33 +0000 schrieb Richard Hughes:
> The packaging guidelines have a single sentence on package summaries:
> https://fedoraproject.org/wiki/Packaging/Guidelines#Summary_and_description
>
> "The summary should be a short and concise description of the package"
>
> Broken packages are a problem as PackageKit shows the summary first (in
> bold) in preference to the package name. This is by design.
And IMO this is wrong by design. Why?
1. Because packages are still sorted by name and not by
description. This makes it very hard to find something.
2. Because in most package managers (at least their GUIs) only
allow to search for name and not for summary.
> Quite a lot of packages have summary text that is overly verbose, and
> this makes the GUI and output from pkcon look rubbish.
+1, so I agree with Michael and Toshio that we should care about the
"foo is a ..." or "is the ..." descriptions first. This will help us to
save space without removing any information. IMO "is a" in summary
should be strictly forbidden by a "hard" guideline.
> For instance, I've filed
> https://bugzilla.redhat.com/show_bug.cgi?id=472365 where the oggconvert
> package has a summary of:
>
> "A simple GNOME application that converts media files to Free formats"
>
> First, we don't need to say it's an application, not that it's GNOME
> specific. Surely something like this would be better:
>
> "Simple media converter"
> or
> "Simple conversion to free media formats"
> or
> "Simple media converter using free formats"
OK, but as others already pointed out we have a couple of "simple media
converters" then and the user will have to read the description to get
an idea of the differences between them.
Today you mailed me because Thunar (which I'm not owning but only
co-maintaining) has the following summary:
Thunar File Manager
So if we remove thunar, nautilus, pcmanfm, ... only "file manager"
remains and I have no idea how to improve this summary.
* "File manager for the Xfce desktop environment"? Not really,
because it's not Xfce specific.
* "Lightweight File Manager"? No, pcmanfm is even more lightweight
* "GTK based File Manager"? We have at least 5 GTK based file
managers
The three file managers are very similar in design and function, so to
me it's almost logical that the descriptions are too. Can you tell me
what to improve in this case?
> The guidelines also don't say if it should be Title Case or if the
> summary should include the application name.
So your are suggesting to forbid the name in summary? Back in those
pirut days I would have agreed to you, but now with PackageKit I'm not
sure if I can still subscribe to your POV. Example:
* abiword The AbiWord word processor
We have a couple of word processors and having the application's name in
the description helps to distinguish between them. What is so bad in
having descriptions like "The exim mail transfer agent", "The postfix
mail transfer agent" and "The sendmail mail transfer agent"?
Also your "simple hacky tool" produces a lot of false positives:
* acpi Command-line ACPI client (try to remove ACPI from summary)
* barcode generates barcodes from text strings
* ccid Generic USB CCID smart card reader driver
* contacts Contacts addressbook
* dialog A utility for creating TTY dialog boxes
The problem with these packages it not the summary but the generic name
of the package. This is something we cannot change.
More examples of false positives:
* asylum SDL port of the game Asylum, originally for the
Archimedes (try to remove the name here: A port of what?)
* audit User space tools for 2.6 kernel auditing
* calc Arbitrary precision arithmetic system and calculator
* dia Diagram drawing program
* ed The GNU line editor
* eject A program that ejects removable media using software
control.
I'm not criticizing your script, I just want to point out that it's not
as many packages as you might think and for others there is nothing we
can do about it.
> If we come to some
> guidelines (or working practices) on this email thread, I'll update the
> wiki page with more details.
OK, so as a start let's forbid "... is a ...". Furthermore as Ignacio
and Toshio pointed out we should get rid of verb phrases. Verb phrases
are ok for descriptions (both in spec and in desktop files) but for
summary we should use nouns.
> It would also be a good idea to have a few "shining examples" for people
> to copy when creating new packages. When we've done that, I'll start
> filing bugs.
>
> Thanks,
>
> Richard.
Regards,
Christoph