To: Debian developers list Subject: Package maintainers please look at your Description fields. dselect will be much more useful when more packages are more informative in the Description they provide in their control file. So, when you next release a package, could you please check whether the `control' file has a good description of the package, formatted as described below ? A small amount of effort here on the part of package maintainers will improve the looks of things quite a bit, I think. BTW, a number of packages have been indenting continuation lines in their Description fields thus: Description: gnomovision Gnomovision is .... further blurb ... Please don't do this. According to the scheme described below (which I've now implemented), dselect interprets the extra indentation to mean `preformatted' text, and doesn't wordwrap it. Ian. The format of the Description field is as follows: Description: The extended description has several kinds of line: - those starting with a single space are part of a paragraph. Successive lines of this form will be word-wrapped when displayed. The leading space will usually be stripped off. - those starting with two or more spaces. These will be displayed verbatim. If the display cannot be panned horizontally the displaying program will linewrap them `hard' (ie, without taking account of word breaks). If it can they will be allowed to trail off to the right. None, one or two initial spaces may be deleted, but the number of spaces deleted from each line will be the same (so that you can have indenting work right, for example). - those containing a single space followed by a single full stop character. These are rendered as blank lines. This is the ONLY way to get a blank line - see below. - those containing a space, a full stop and some more characters. These are for future expansion. Don't use them. IMPORTANT and not so important TIPS: * ALWAYS START EXTENDED DESCRIPTION LINES WITH AT LEAST ONE WHITESPACE CHARACTER. Fields in the control file and in the Packages file are separated by field names starting in the first column, just as in RFC822. Forgetting the whitespace will cause dpkg-deb (>=0.93.23) to produce a syntax error when trying to build the package. If you force it to build anyway dpkg will refuse to install the resulting mess. * DO NOT INCLUDE ANY COMPLETELY EMPTY LINES. These separate different records in the Packages file, and are forbidden in control files. See the previous paragraph for what happens if you get this wrong. * The single line synopsis should be kept brief - certainly under 80 characters. My current working half-dselect displays the first 49 characters if you're using an 80-column terminal. * Don't include the package name in the synopsis line. The display software knows how to display this already, and you don't need to state it. * The extended description should describe what the package does, and what component it forms of any larger subsystem of which it is a part. * Put important information first, both in the synopis and extended description. Sometimes only the first part of the synopsis or of the description will be displayed. You can assume that there will usually be a way to see the whole extended description. * You may include information about dependencies and so forth in the extended description, if you wish. * Don't use tab characters. Their effect is not predictable. Example control file for Smail: Package: smail Version: 3.1.29.1 Package_Revision: 8 Maintainer: Ian Jackson Recommended: pine | elm | emacs | mh | mailx Optional: metamail Depends: cron Conflicts: sendmail Description: Electronic mail transport system. Smail is the recommended mail transport agent (MTA) for Debian. . An MTA is the innards of the mail system - it takes messages from user-friendly mailer programs and arranges for them to be delivered locally or passed on to other systems as required. . In order to make use of it you must have one or more user level mailreader programs such as elm, pine, mailx or Emacs (which has Rmail and VM as mailreaders) installed. If you wish to send messages other than just to other users of your system you must also have appropriate networking support, in the form of IP or UUCP. -- Ian Jackson, at home. ijackson@nyx.cs.du.edu or iwj10@cus.cam.ac.uk +44 1223 575512 Escoerea on IRC. http://www.cl.cam.ac.uk/users/iwj10/ 2 Lexington Close, Cambridge, CB4 3LS, England. Urgent: iwj@cam-orl.co.uk