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 -- fedora-devel-list mailing list fedora-devel-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/fedora-devel-list
