Re: description writing guide
On 07-Dec-02, 16:05 (CST), David B Harris [EMAIL PROTECTED] wrote: On Sat, 7 Dec 2002 11:51:03 +0100 Martin Schulze [EMAIL PROTECTED] wrote: It is a bad practice to repeat the package name as the first word in the long description. Why is that again? Because anything[1] that displays the long description also displays the package name right next to it. (Althought I think putting in the long description is less of a problem than in the short description, which is often displayed in situations of limited space.) Steve [1] Ignoring special cases like dpkg-grep-available, or whatever it's called. -- Steve Greenland The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. -- seen on the net
Re: description writing guide
Colin Walters wrote: Hello, I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to comment on new package descriptions, but I finally sat down and committed my thoughts on description writing in a semi-coherent form: http://people.debian.org/~walters/descriptions.html Please have a look at this if you're creating a new package now, and fixing packages you currently maintain would be great too :) Your example lists: Package: foo Description: perform some function, do some task for GNOME/KDE/WindowMaker/GNU/Linux foo is a function program, designed to help you task. more simple details about task. Written for the environment, it supports feature1 and feature2. [..] . You can find more information about foo at http://www.foo.org. It is a bad practice to repeat the package name as the first word in the long description. Also the URL does not belong into the description but should be placed in the debian/copyright file instead. To quote Joey Hess: The Description field is not intended to be a random dumping-ground for any information that cannot fit into some other field. Regards, Joey -- No question is too silly to ask, but, of course, some are too silly to answer. -- Perl book Please always Cc to me when replying to me on the lists.
Re: description writing guide
* Martin Schulze ([EMAIL PROTECTED]) wrote: Your example lists: Package: foo Description: perform some function, do some task for GNOME/KDE/WindowMaker/GNU/Linux foo is a function program, designed to help you task. more simple details about task. Written for the environment, it supports feature1 and feature2. [..] . You can find more information about foo at http://www.foo.org. It is a bad practice to repeat the package name as the first word in the long description. Also the URL does not belong into the description but should be placed in the debian/copyright file instead. What if someone wants to visit the webpage before they install a package, to decide whether it's worth downloading or not (especially if their bandwidth is slow and expensive)? -- Josh Haberman Debian GNU/Linux developer
Re: description writing guide
On Sat, 2002-12-07 at 05:51, Martin Schulze wrote: It is a bad practice to repeat the package name as the first word in the long description. Fair enough. Fixed. Also the URL does not belong into the description but should be placed in the debian/copyright file instead. To quote Joey Hess: The Description field is not intended to be a random dumping-ground for any information that cannot fit into some other field. I think this is somewhat controversial. Having them in the debian/copyright file doesn't help people who are just browsing the packages in aptitude or whatever. So I added whether or not a URL should go in to the controversial section.
Re: description writing guide
Joshua Haberman wrote: It is a bad practice to repeat the package name as the first word in the long description. Also the URL does not belong into the description but should be placed in the debian/copyright file instead. What if someone wants to visit the webpage before they install a package, to decide whether it's worth downloading or not (especially if their bandwidth is slow and expensive)? He visits http://packages.debian.org/$package and some day it will display URLs as well. Regards, Joey -- Those who don't understand Unix are condemned to reinvent it, poorly. Please always Cc to me when replying to me on the lists.
Re: description writing guide
On Sat, 7 Dec 2002 11:51:03 +0100 Martin Schulze [EMAIL PROTECTED] wrote: It is a bad practice to repeat the package name as the first word in the long description. Why is that again? Also the URL does not belong into the description but should be placed in the debian/copyright file instead. Joey might have said that, but I believe the consensus was it's a nice feature. The description is not a random dumping-ground for information, but what information we include is entirely arbitrary. If people like having the URL in the description (and they do), there's no reason why it shouldn't be included unless you want to make a case for Packages.gz bloat. pgp8Qr6wqeOwI.pgp Description: PGP signature
Re: description writing guide
On Sat, Dec 07, 2002 at 11:51:03AM +0100, Martin Schulze wrote: It is a bad practice to repeat the package name as the first word in the long description. Actually it's bad in the short description, not necessarily in the long one. Also the URL does not belong into the description but should be placed in the debian/copyright file instead. To quote Joey Hess: The Description field is not intended to be a random dumping-ground for any information that cannot fit into some other field. You leave out the part where we agreed on having it _both_ in the copyright file and in a new field of the control file. (That whole thread was wrongly summarized in DWN recently.) -- 2. That which causes joy or happiness.
Re: description writing guide
Martin Schulze [EMAIL PROTECTED] wrote: Joshua Haberman wrote: It is a bad practice to repeat the package name as the first word in the long description. Also the URL does not belong into the description but should be placed in the debian/copyright file instead. What if someone wants to visit the webpage before they install a package, to decide whether it's worth downloading or not (especially if their bandwidth is slow and expensive)? He visits http://packages.debian.org/$package and some day it will display URLs as well. Once that happens I'll remove the URL from the package description, which gives me the URL on packages.debian.org /now/. cu andreas
Re: description writing guide
Steve Greenland [EMAIL PROTECTED] writes: 1. I suspect it will be very hard to get this consistently used in Debian descriptions, as there are a lot of people who do not naturally use the 'period-two-spaces' convention. (I suspect it is entirely determined by how much typing one did on real typewriters, pre-wordprocessor.) So let's just require it for descriptions, shall we? It's already what Emacs uses, and it actually works, and is widespread use. We can fix the bugs as we find them, just like anything else. 2. IMO, the naive rendering of .spsp looks fairly dreadful in variable-width fonts -- they'd need to strip out the extra space and do it correctly. (Actually, IMO, it looks fairly dreadful in fixed width fonts, too). Um, so the *renderer* has the job of doing this right, right?
Re: description writing guide
Steve Greenland [EMAIL PROTECTED] wrote: On 05-Dec-02, 16:49 (CST), Thomas Bushnell, BSG [EMAIL PROTECTED] wrote: It is not possible for an automated renderer to figure out where sentence boundaries are without some kind of help, and a mere period is not sufficient help. So, a good convention to establish might be that the string . indicates the end of a sentence, and . does not. While technically valid, I don't like his much, for a couple of reasons: 1. I suspect it will be very hard to get this consistently used in Debian descriptions, as there are a lot of people who do not naturally use the 'period-two-spaces' convention. (I suspect it is entirely determined by how much typing one did on real typewriters, pre-wordprocessor.) [...] Because nobody else has noted it yet I'll add it: It is also depending on whether the peoople are English/American/etc. or not. For example it is not usual in French and German texts to have bigger whitespace at sentence boundaries. See \frenchspacing in TeX. cu andreas
Re: description writing guide
On Thu, Dec 05, 2002 at 03:23:08PM -0500, David B Harris wrote: On Thu, 5 Dec 2002 20:59:09 +0100 Javier Fernández-Sanguino Peña [EMAIL PROTECTED] wrote: a good search interface in our package interface UIs (good search != search by words). ... as opposed to searching based on the contents of people's minds? :) Probably :) I should have said keywords instead of words. That is, it's not the same to search for game multiplayer (keywords) than a game that let's me play with other people (natural language) :-) Javi pgpOJIKNtu5fb.pgp Description: PGP signature
Re: description writing guide
On Thu, Dec 05, 2002 at 11:12:17PM -0500, Colin Walters wrote: On Thu, 2002-12-05 at 14:59, Javier Fernández-Sanguino Peña wrote: Not only users, software might use them too. We currently don't have a good search interface in our package interface UIs (good search != search by words). I tried to make (quite a long time ago and it's pretty much an experiment) a search UI based on an artificial intelligence approach (that is, TFIDF document organisation). Interesting! It would be cool if aptitude included something like this. I'm sorry I can't offer new code (including aptitute integration), I have gone (Debian-wise) _way_ beyond what I handle on my own. So, if somebody is interested on this approach I could offer advice/help. Any takers? Javi pgpu25uDlyeKW.pgp Description: PGP signature
Re: description writing guide
Steve Greenland wrote: While technically valid, I don't like his much, for a couple of reasons: 1. I suspect it will be very hard to get this consistently used in Debian descriptions, as there are a lot of people who do not naturally use the 'period-two-spaces' convention. (I suspect it is entirely determined by how much typing one did on real typewriters, pre-wordprocessor.) 2. IMO, the naive rendering of .spsp looks fairly dreadful in variable-width fonts -- they'd need to strip out the extra space and do it correctly. (Actually, IMO, it looks fairly dreadful in fixed width fonts, too). Don't forget: 3. It can easily fails if a sentence happens to end at the end of a line. Like the previous sentence, which only a computer programmer would think to add two spaces at the end of. :-) -- see shy jo pgpaw18Y2J4Mv.pgp Description: PGP signature
Re: description writing guide
On 06-Dec-02, 11:25 (CST), Joey Hess [EMAIL PROTECTED] wrote: Don't forget: 3. It can easily fails if a sentence happens to end at the end of a line. Like the previous sentence, which only a computer programmer would think to add two spaces at the end of. :-) Nah, programmers know that whitespace (1) is syntactically irrelevant, and will *never* get it right! :-) Steve -- Steve Greenland The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. -- seen on the net
Re: description writing guide
Joey Hess [EMAIL PROTECTED] wrote:
Don't forget:
3. It can easily fails if a sentence happens to end at the end of a line.
Like the previous sentence, which only a computer programmer would
think to add two spaces at the end of. :-)
Not if you also require abbreviations to not extend across lines, i.e.,
U. S. A. rather than U.
S. A.
--
Debian GNU/Linux 3.0 is out! ( http://www.debian.org/ )
Email: Herbert Xu ~{PmVHI~} [EMAIL PROTECTED]
Home Page: http://gondor.apana.org.au/~herbert/
PGP Key: http://gondor.apana.org.au/~herbert/pubkey.txt
Re: description writing guide
Herbert Xu wrote: Don't forget: 3. It can easily fails if a sentence happens to end at the end of a line. Like the previous sentence, which only a computer programmer would think to add two spaces at the end of. :-) Not if you also require abbreviations to not extend across lines, i.e., U. S. A. rather than U. S. A. The reader wonders about ending a line using Mr. Herbert Xu's method -- does it truely avoid all sentence parsing ambiguity? Should a dumb program render this reply as two sentences, or as three? -- see shy jo pgpexSNyRQRlI.pgp Description: PGP signature
Re: description writing guide
On Wed, Dec 04, 2002 at 08:05:43PM -0500, Colin Walters wrote: I think this is hard to without switching to a format which allows us to include more metadata (like XML). So we can explicitly use stuff like ul and li for lists, instead of relying on ASCII renderings. That way we can safely word-wrap the description, instead of just treating it as the equivalent of pre. The Description file used to have such a format. It had enough information to allow word-wrapping, a specified format for bulleted lists, and a way to add meta-information (even though no such information was yet defined). Sadly, it seems to have been lost. I can't find a description of the Description format anywhere in the current policy manual; not even in the version of the Packaging Manual that it carries as an appendix. Hmm, D.2.7 says the description is in a special format, but does not say what that format is, and refers to a section that does not describe it. Richard Braakman
Re: description writing guide
On Wed, Dec 04, 2002 at 12:55:50PM -0500, Colin Walters wrote: I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to comment on new package descriptions, but I finally sat down and committed my thoughts on description writing in a semi-coherent form: In the DDTP I collect some rules about the descriptions. You can find this on the end of the FAQ. (http://ddtp.debian.org/ddtp-text/misc/ddts-faq.txt) Maybe this help Gruss Grisu -- Michael Bramer - a Debian Linux Developer http://www.debsupport.de PGP: finger [EMAIL PROTECTED] -- Linux Sysadmin -- Use Debian Linux The UNIX Guru's View of Sex: gawk; talk; nice; date; wine; grep;\ touch; unzip; strip; touch; gasp; finger; gasp; mount; fsck; more;\ yes; gasp; umount; make clean; make mrproper; sleep pgptsa4s0CmWw.pgp Description: PGP signature
Re: description writing guide
Am 4.12.02 um 15:15:53 schrieb David B Harris: If variable-width fonts are used, then line breaks shouldn't be preserved. If they're not going to be preserved, there needs to be a very specific set of rules as to how lines are joined. These already exist in code, actually; I believe packages.debian.org joins lines. Line breaks already aren't preserved, and there already exist a very specific set of rules for that. Look into your documentation, and have a look at dselect. Cheers, Mike -- |=| Michael Piefel |=| Humboldt-Universität zu Berlin |=| Tel. (+49 30) 2093 3831
Re: description writing guide
Am 4.12.02 um 14:38:07 schrieb Joey Hess: angband: Sauron [...] most powerful of his servants Nice script, Joey, but perhaps you should have looked at the description for yourself. :-) Cheers, Mike -- |=| Michael Piefel |=| Humboldt-Universität zu Berlin |=| Tel. (+49 30) 2093 3831
Re: description writing guide
On Wed, Dec 04, 2002 at 07:19:38PM +, Scott James Remnant wrote: In correct English grammar and typography the space after a full stop (period in Merkin) is supposed to be a wider space then that between words and after commas and suchlike. There is no such thing as correct typography, only current typographical conventions, which vary with time, place, context, font, purpose and so on. For example, while many good typographers do insert extra space between sentences, many don't. See, for example, Robert Bringhurst's The Elements of Typographic Style for someone who argues against extra space. Julian -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Julian Gilbey, website: http://www.polya.uklinux.net/ Debian GNU/Linux Developer, see: http://people.debian.org/~jdg/ Visit http://www.thehungersite.com/ to help feed the hungry
Re: description writing guide
On Thu, Dec 05, 2002 at 12:18:08PM +0100, Michael Piefel wrote: Am 4.12.02 um 14:38:07 schrieb Joey Hess: angband: Sauron [...] most powerful of his servants Nice script, Joey, but perhaps you should have looked at the description for yourself. :-) Heh, I succesfully managed to :q! when I saw joeyh commented on Sauron further down ;) Michael -- weasel we should propose to rename the FSG to DFSG as our first action
Re: description writing guide
On Wed, Dec 04, 2002 at 02:09:50PM -0500, Joey Hess wrote: Ari Pollak wrote: I think the real issue here isn't so much actual package descriptions, but the ITPs. Most package descriptions I've seen have been pretty accurate, and tend to change a lot between the time of the ITP and actual package release. I disagree. Every time I look at the descriptions of a dozen new packages in the archive, I can file at least half a dozen bug reports, if I find the time (I've filed several hundred so far). Package descriptions tend to continue to suck. I'd be willing to invest some time in co-maintenance of a package description override list. -- - mdz
Re: description writing guide
David B Harris wrote: If variable-width fonts are used, then line breaks shouldn't be preserved. If they're not going to be preserved, there needs to be a very specific set of rules as to how lines are joined. These already exist in code, actually; I believe packages.debian.org joins lines. I think that the exact documentation of the formatting options available to the extended description fields is not with us as a consequence of the ill-advised dropping of the Packaging Manual. Yes the rules exist, have been written down (and then apparently that documentation thrown away), are used in aptitude, dselect, and various other programs, etc. -- see shy jo pgpodYlQl8fPN.pgp Description: PGP signature
Re: description writing guide
On Wed, Dec 04, 2002 at 07:59:20PM -0500, Colin Walters wrote: [snip] Ooh, goody :) Does this mean #45943 will finally be fixed? Well, we obviously can't force anyone to do anything; but I hope that having the reasoning more clearly laid out will motivate people... [snip] Does submitting a diff -u patch for #45943 constitute motivation as well? 'Cos that's what I'm thinking of doing, at the moment. Prepare an NMU, send in the patch, email the maintainer, etc., except actually uploading it. (If that's what it takes, that is.) T -- You've gotten under my skin. That you got there speaks ill of me. That you like it there speaks ill of you. -- Speek, K5
Re: description writing guide
Matt Zimmerman wrote: I'd be willing to invest some time in co-maintenance of a package description override list. I've had a pretty good amount of response to my description bug reports. -- see shy jo pgpkDFlipLeZ5.pgp Description: PGP signature
Re: description writing guide
On Wed, Dec 04, 2002 at 12:55:50PM -0500, Colin Walters wrote: Hello, I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to (...) Not only users, software might use them too. We currently don't have a good search interface in our package interface UIs (good search != search by words). I tried to make (quite a long time ago and it's pretty much an experiment) a search UI based on an artificial intelligence approach (that is, TFIDF document organisation). This kind of software _needs_ to have good descriptions to be useful at all otherwise natural language processing of descriptions does not give any benefit to the user. So, in summary, I think your proposal is pretty good and could IMHO, be included in our policy. That is to say, http://www.debian.org/doc/debian-policy/ch-archive.html#s2.3.3 probably needs to be extended further to include these recommendations. Regards Javi PS: The package, if you are curious, is called 'dpkg-iasearch' BTW. pgpD3iXRWLA1y.pgp Description: PGP signature
Re: description writing guide
On Thu, Dec 05, 2002 at 01:58:43PM -0500, Joey Hess wrote: Matt Zimmerman wrote: I'd be willing to invest some time in co-maintenance of a package description override list. I've had a pretty good amount of response to my description bug reports. But do your bug reports keep up with the flow of new packages into the archive? That is, is the overall description quality increasing or decreasing? My subjective experience is that it is decreasing. When I encounter a package that I have not seen before, its description is poor more often than not. -- - mdz
Re: description writing guide
On Thu, 5 Dec 2002 12:13:57 +0100 Michael Piefel [EMAIL PROTECTED] wrote: Line breaks already aren't preserved, and there already exist a very specific set of rules for that. Look into your documentation, and have a look at dselect. I already have example applications which don't preserve them :) packages.d.o was just one such example. Could you point me at the documentation in question? pgpZ1ILPPpLkT.pgp Description: PGP signature
Re: description writing guide
On Thu, 5 Dec 2002 20:59:09 +0100 Javier Fernández-Sanguino Peña [EMAIL PROTECTED] wrote: a good search interface in our package interface UIs (good search != search by words). ... as opposed to searching based on the contents of people's minds? :) pgphxF5io44ke.pgp Description: PGP signature
Re: description writing guide
On Thu, 5 Dec 2002, Matt Zimmerman wrote: On Thu, Dec 05, 2002 at 01:58:43PM -0500, Joey Hess wrote: Matt Zimmerman wrote: I'd be willing to invest some time in co-maintenance of a package description override list. I've had a pretty good amount of response to my description bug reports. But do your bug reports keep up with the flow of new packages into the archive? That is, is the overall description quality increasing or decreasing? There are others that are writing bugreports against package descriptions. I do it about every second time I do an package list update. I fear being too pedantic, but I haven't met any angrynes yet. So far positive. *t -- to ma will kill for oil s p
Re: description writing guide
Steve Greenland [EMAIL PROTECTED] writes: However, this is all on *output* (display, whatever). The input text should have just a single space. The text has to be reformatted to fit the screen (display area) anyway (even on a terminal), and it's the job of the reformatter/text renderer/whatever to get it right. It is not possible for an automated renderer to figure out where sentence boundaries are without some kind of help, and a mere period is not sufficient help. So, a good convention to establish might be that the string . indicates the end of a sentence, and . does not.
Re: description writing guide
On Thu, Dec 05, 2002 at 10:03:32PM +0100, tomas pospisek [EMAIL PROTECTED] was heard to say: On Thu, 5 Dec 2002, Matt Zimmerman wrote: But do your bug reports keep up with the flow of new packages into the archive? That is, is the overall description quality increasing or decreasing? There are others that are writing bugreports against package descriptions. I do it about every second time I do an package list update. I fear being too pedantic, but I haven't met any angrynes yet. So far positive. I was doing it for a while too, but I fear Matt may be correct. We aren't keeping up with the rate at which people are shovel^Wadding stuff into the archive. Daniel -- / Daniel Burrows [EMAIL PROTECTED] ---\ | Whoever fights monsters should see to it that in the | | process he does not become a monster. And when you look | | into an abyss, the abyss also looks into you. | | -- Friedrich Nietzsche| \ Be like the kid in the movie! Play chess! -- http://www.uschess.org ---/
Re: description writing guide
On 05-Dec-02, 16:49 (CST), Thomas Bushnell, BSG [EMAIL PROTECTED] wrote: It is not possible for an automated renderer to figure out where sentence boundaries are without some kind of help, and a mere period is not sufficient help. So, a good convention to establish might be that the string . indicates the end of a sentence, and . does not. While technically valid, I don't like his much, for a couple of reasons: 1. I suspect it will be very hard to get this consistently used in Debian descriptions, as there are a lot of people who do not naturally use the 'period-two-spaces' convention. (I suspect it is entirely determined by how much typing one did on real typewriters, pre-wordprocessor.) 2. IMO, the naive rendering of .spsp looks fairly dreadful in variable-width fonts -- they'd need to strip out the extra space and do it correctly. (Actually, IMO, it looks fairly dreadful in fixed width fonts, too). (Of course, if this is the worst problem we have with Debian package descriptions, I say flip a coin and forget about it.) Steve -- Steve Greenland The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. -- seen on the net
Re: description writing guide
On Thu, Dec 05, 2002 at 03:21:24PM -0500, David B Harris [EMAIL PROTECTED] was heard to say: On Thu, 5 Dec 2002 12:13:57 +0100 Michael Piefel [EMAIL PROTECTED] wrote: Line breaks already aren't preserved, and there already exist a very specific set of rules for that. Look into your documentation, and have a look at dselect. I already have example applications which don't preserve them :) packages.d.o was just one such example. Could you point me at the documentation in question? I think it used to be in the Developer's Reference, Policy, or the Packaging Guide. I'd check those -- although I wasn't able to find it last time I wanted to refer to it. Basically, all lines in a long description start with (at least) one space, paragraphs are separated by a line containing only a period, and lines starting with two spaces are formatted literally and not word-wrapped. Oh, and lines beginning with a period which contain other letters are reserved for future expansion. There may be more, I don't remember perfectly. Daniel -- / Daniel Burrows [EMAIL PROTECTED] ---\ | Note that fires are not restricted to dormitories. | | Indeed, fire can occur in off-campus residences as well. | | -- Brown University Fire Safety Guide | \ Be like the kid in the movie! Play chess! -- http://www.uschess.org ---/
Re: description writing guide
On Thu, Dec 05, 2002 at 02:49:12PM -0800, Thomas Bushnell, BSG wrote: It is not possible for an automated renderer to figure out where sentence boundaries are without some kind of help, and a mere period is not sufficient help. So, a good convention to establish might be that the string . indicates the end of a sentence, and . does not. I was about to say that, but then I realized that it doesn't help if a period is at the end of a line. I use two spaces between sentences myself (old emacs habit), but it irks me that that's not a complete solution. Richard Braakman
Re: description writing guide
Steve Greenland wrote: (Of course, if this is the worst problem we have with Debian package descriptions, I say flip a coin and forget about it.) I have a better idea -- just forget it altogether. It doesn't need to be standardized in Debian; it certainly isn't standardized in the publishing industry, which has more need to worry about typographic quality than Debian needs to be. An extra space character, or the absence of one, hurts nobody. Craig
Re: description writing guide
David B Harris writes: Could you point me at the documentation in question? Debian Packaging Manual --- Ian Jackson [EMAIL PROTECTED] Revised: David A. Morris [EMAIL PROTECTED] Maintainer: Christian Schwarz [EMAIL PROTECTED] Maintainer: Manoj Srivastava [EMAIL PROTECTED] Maintainer: The Debian Policy group debian-policy@lists.debian.org version 3.1.1.1, 1999-11-22 ... ... ... 7. Descriptions of packages - the `Description' field - The `Description' control file field is used by `dselect' when the user is selecting which packages to install and by `dpkg' when it displays information about the status of packages and so forth. It is included on the FTP site in the `Packages' files, and may also be used by the Debian WWW pages. The description is intended to describe the program to a user who has never met it before so that they know whether they want to install it. It should also give information about the significant dependencies and conflicts between this package and others, so that the user knows why these dependencies and conflicts have been declared. The field's format is as follows: Description: single line synopsis extended description over several lines The synopsis is often printed in lists of packages and so forth, and should be as informative as possible. Every package should also have an extended description. 7.1. Types of formatting line in the extended description - * 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 correctly, 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. Do not use them. 7.2. Notes about writing descriptions - _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 message header fields are in RFC822. Forgetting the whitespace will cause `dpkg-deb' [1] 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. [1] Version 0.93.23 or later. _Do not_ include any completely _empty_ lines. These separate different records in the Packages file and different packages in the `debian/control' file, and are forbidden in package 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. `dselect' displays between 25 and 49 characters without panning if you're using an 80-column terminal, depending on what display options are in effect. Do not include the package name in the synopsis line. The display software knows how to display this already, and you do not need to state it. Remember that in many situations the user may only see the synopsis line - make it as informative as you can. The extended description should describe what the package does and how it relates to the rest of the system (in terms of, for example, which subsystem it is which part of). The blurb that comes with a program in its announcements and/or `README' files is rarely suitable for use in a description. It is usually aimed at people who are already in the community where the package is used. The description field needs to make sense to anyone, even people who have no idea about any of the things the package deals with. 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
Re: description writing guide
On Thu, Dec 05, 2002 at 02:49:12PM -0800, Thomas Bushnell, BSG wrote: Steve Greenland [EMAIL PROTECTED] writes: However, this is all on *output* (display, whatever). The input text should have just a single space. The text has to be reformatted to fit the screen (display area) anyway (even on a terminal), and it's the job of the reformatter/text renderer/whatever to get it right. It is not possible for an automated renderer to figure out where sentence boundaries are without some kind of help, and a mere period is not sufficient help. So, a good convention to establish might be that the string . indicates the end of a sentence, and . does not. I think *roff's trick of put a line break after the full stop at the end of a sentence would be better. That way current frontends don't have to change (normal word-wrapping will sort it out) unless they take the decision that their output looks better with two spaces, at which point it's trivial to do so. (Easy things should be easy, and hard things possible.) -- Colin Watson [EMAIL PROTECTED]
Re: description writing guide
On Wed, 2002-12-04 at 14:38, Joey Hess wrote: Your emphasis on audiences is very good, but I am leery of the treatment of package descriptions as advertisements. A package description that reads like an in-your-face advertisement can suck at being a package description. You're right in some ways about the correspondance, but I think the thing you leave out is that these are advertisements that are aimed at getting only the users who should install a package to install it, not all users, and that if the advertisement gets accross to someone that this is probably not the package they want, it is also doing its job. Particularly if it helps them find the package they _do_ want. These are not features of traditional commercial advertisements. Insert some mumbling about zero-sum games here. Ok, I changed the guide a bit more to emphasize a bit more that descriptions should also be useful. The easiest problem to point to WRT description-as-advertisement is it encourages the insertation of useless superlatives into the description, as you do in the example template when you say foo is a powerful... Ok, people don't really like the powerful sample adjective, apparently :) I've dropped it. Look at the uses of powerful in existing descriptions, for example, and see how many you agree with: Yeah, I know. I'd rather that our descriptions were more objective and weren't afraid to say hey, if you're looking for a really good foo and don't have specialized needs x y and z, you probably want bar instead. Ok, I mentioned that in the guide too.
Re: description writing guide
Steve Greenland [EMAIL PROTECTED] writes: In standard typography, it is to have extra space after a period ending a sentence. For fixed-width fonts, this often shows up as two spaces, as is fairly ugly. Of course, that's simply an opinion, and depends a lot on exactly _which_ fixed fonts you use -- I find that text with only a single space after the period much harder to read, at least with the fixed-width fonts I use. OTOH a lot of people (IMO) would argue that the fixed-width two-space end of sentence is sufficiently ugly that we're better off without it. ... and a lot of other people will argue exactly the opposite. [In other words, it's a matter of taste, and both methods should be supported where feasible.] -Miles -- P.S. All information contained in the above letter is false, for reasons of military security.
Re: description writing guide
On Wed, 2002-12-04 at 20:26, Simon Richter wrote: Colin, http://people.debian.org/~walters/descriptions.html Well, I'm not sure there should be a template -- people will use it (and thus try to squeeze information into it). I usually tell my sponsees that a description should answer the following questions, roughly in that order: Thanks Simon; I've created a checklist section, incorporating this.
Re: description writing guide
On Thu, 2002-12-05 at 14:59, Javier Fernndez-Sanguino Pea wrote: Not only users, software might use them too. We currently don't have a good search interface in our package interface UIs (good search != search by words). I tried to make (quite a long time ago and it's pretty much an experiment) a search UI based on an artificial intelligence approach (that is, TFIDF document organisation). Interesting! It would be cool if aptitude included something like this. This kind of software _needs_ to have good descriptions to be useful at all otherwise natural language processing of descriptions does not give any benefit to the user. Makes sense. So, in summary, I think your proposal is pretty good and could IMHO, be included in our policy. That is to say, http://www.debian.org/doc/debian-policy/ch-archive.html#s2.3.3 probably needs to be extended further to include these recommendations. Cool, I'm glad you like it. However, I think general consensus of the policy editors is to make policy a lean, core document, and then have stuff like recommendations for description writing in the packaging manual. So maybe once that packaging manual is created (it doesn't exist yet, right?), we can move stuff in there.
description writing guide
Hello, I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to comment on new package descriptions, but I finally sat down and committed my thoughts on description writing in a semi-coherent form: http://people.debian.org/~walters/descriptions.html Please have a look at this if you're creating a new package now, and fixing packages you currently maintain would be great too :) Comments appreciated, of course.
Re: description writing guide
I think the real issue here isn't so much actual package descriptions, but the ITPs. Most package descriptions I've seen have been pretty accurate, and tend to change a lot between the time of the ITP and actual package release. Colin Walters wrote: I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to comment on new package descriptions, but I finally sat down and committed my thoughts on description writing in a semi-coherent form:
Re: description writing guide
On 04 Dec 2002 12:55:50 -0500 Colin Walters [EMAIL PROTECTED] wrote: http://people.debian.org/~walters/descriptions.html Thanks. pgpfyKOIrBIap.pgp Description: PGP signature
Re: description writing guide
On 04 Dec 2002 12:55:50 -0500 Colin Walters [EMAIL PROTECTED] wrote: http://people.debian.org/~walters/descriptions.html I do have some differences of opinion, though. It's sad, but there are a getting to be a fairly large number of DDs who are attention grabbers. Just a few days ago, I saw a package description that said something along the lines of this is the best package for this purpose ... and it certainly wasn't. Even if it was, I think everybody would agree that that kind of language doesn't belong in a Debian package description. So, the opening section that talks about advertising and whatnot will probably give these sorts of people the wrong idea; I'd ammend it to: Debian package descriptions are the first avenue for you to give your audience relevant, useful information about your package. When you attempt to give somebody new knowledge, the key idea is to emknow your audience/em. Also, I'm not sure I agree with the third paragraph; everything in it is factual and well-said, but it'd be nice if somebody who *didn't* know what GTK+ and RAD are could know conclusively, this is not what I want. When you're looking for something specific, but don't know the exact package name, the process of elimination is the best start. I know I, *personally*, have installed packages which I couldn't immediately rule out from the package description because I didn't *quite* understand the jargon. glade is a bad example for my point, though, because it has a great description :) In paragraph five (So how can we better target these users?), I'd s/minimum/appropriate amount/. I've seen bloody jihads in very well-known projects to give only the minimum of technical jargon, and people invariably take it to far. Had they just stressed appropriateness of the text to the audience, things would have been much more reasonable. In paragraph six, (So far we've mainly discussed the synopsis line), I'd s/competition/alternatives/; s/advertisement/good documentation/. (BTW, if you totally disagree with me about this advertisement stuff, do replace all references to advertisements with good advertisements and whatnot :) Also, in the description template, two spaces are used after a period - is that standard nowadays? (My understanding was that they were primarily used for variable-width fonts, where a single space would take up very little page space. Since the descriptions should be presented in a fixed-width font (for many reasons, this also includes GUI package browsers), they're a bit redundant.) Thanks again :) pgpvz7X4QJZE4.pgp Description: PGP signature
Re: description writing guide
On 04-Dec-02, 12:11 (CST), Ari Pollak [EMAIL PROTECTED] wrote: I think the real issue here isn't so much actual package descriptions, but the ITPs. Most package descriptions I've seen have been pretty accurate, and tend to change a lot between the time of the ITP and actual package release. Because people spend the time to reply to the ITPs correcting the descriptions, presumably duplicating what is in Colin's proposed guide. Hopefully we'll put the guide somewhere that it can be found by most people before they ITP, and people can just point to the guide when a poor ITP description shows up. Steve -- Steve Greenland The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. -- seen on the net
Re: description writing guide
Le mer 04/12/2002 à 19:11, Ari Pollak a écrit : I think the real issue here isn't so much actual package descriptions, but the ITPs. Most package descriptions I've seen have been pretty accurate, and tend to change a lot between the time of the ITP and actual package release. The problem is more in existing package descriptions than in new packages. Bugs should be submitted when the description is not accurate (see the module-init-tools description for an example). -- .''`. Josselin Mouette/\./\ : :' : [EMAIL PROTECTED] `. `'[EMAIL PROTECTED] `- Debian GNU/Linux -- The power of freedom signature.asc Description: PGP signature
Re: description writing guide
On Wed, 2002-12-04 at 19:01, David B Harris wrote: Also, in the description template, two spaces are used after a period - is that standard nowadays? (My understanding was that they were primarily used for variable-width fonts, where a single space would take up very little page space. Since the descriptions should be presented in a fixed-width font (for many reasons, this also includes GUI package browsers), they're a bit redundant.) In correct English grammar and typography the space after a full stop (period in Merkin) is supposed to be a wider space then that between words and after commas and suchlike. Therefore typists were always taught to press the space key twice after a full stop. This rule applies to any *fixed*-width font. So it would be correct to use two spaces after the full stop in a package description, because those are renfered with a fixed-width font. If you are writing text in something that uses variable width fonts, the program should know about English grammar and render the wider space itself on any whitespace. (LaTeX is about the only thing that gets it right though). (If this is wrong, blame the secretary I just asked :) Scott -- Scott James Remnant Have you ever, ever felt like this? Had strange http://netsplit.com/ things happen? Are you going round the twist? signature.asc Description: This is a digitally signed message part
Re: description writing guide
David B Harris wrote: Also, in the description template, two spaces are used after a period - is that standard nowadays? (My understanding was that they were primarily used for variable-width fonts, where a single space would take up very little page space. There was an interesting discussion about this in debian-user a few months back, with inconclusive results. People who learned to type on mechanical typewriters with fixed-width fonts generally were taught to use two spaces between sentences (and perhaps after colons as well). So to say that two spaces were primarily used for variable-width fonts is historically wrong; if anything, they were, and are, more commonly used with fixed-width fonts. Technical writing teachers usually go out of their way to get their students to unlearn the two-spaces rule, and use only one space. I do not know whether this is related to the fact that most documents produced by technical writers are typeset with variable-width fonts. During the debian-user thread on this subject, I did a quick survey of several professionally-typeset books that were near at hand at the time. IIRC, I found that about 70-80% of them did not use extra space between sentences. This seems like enough to show that the general bias in typesetting is to use a single space between sentences, but it also shows that it's not an absolute. As you can see from this message, I have completely given up on two spaces, and always put only one space between sentences. I originally learned to type on a typewriter, and was told to use two spaces; I did this religiously until I did some technical writing and was told by the other tech writers on staff to use only one space. I then observed that my documents looked better without the extra space leaving ugly holes in my paragraphs, and that most books and magazines didn't have the extra space. I have been a single-space writer ever since. Since the descriptions should be presented in a fixed-width font (for many reasons, this also includes GUI package browsers), they're a bit redundant.) I don't see any reason why package descriptions shouldn't be presented in variable-width fonts. The right margin might look a bit ragged (assuming the program preserves line breaks, which is probably a good idea to avoid messing up bulletted lists in the description), but so what? Package descriptions don't usually include tabular data that would be seriously messed up by variable-width fonts. Craig
Re: description writing guide
Scott James Remnant wrote: In correct English grammar and typography the space after a full stop (period in Merkin) is supposed to be a wider space then that between words and after commas and suchlike. Therefore typists were always taught to press the space key twice after a full stop. This rule applies to any *fixed*-width font. So it would be correct to use two spaces after the full stop in a package description, because those are renfered with a fixed-width font. They are? Everywhere? By everyone? I would probably agree that _most_ package managers (especially non-GUI ones, of course) display descriptions in a fixed-width font, but you can't guarantee that they all do. Nor am I aware of anything in Debian policy that says they should. I suppose you could argue that the convention should be in accordance with the most common user experience, but the whole idea of having different rules for fixed vs. variable-width fonts runs into trouble when you don't know what kind of font will ultimately be used by any given user's configuration. If you are writing text in something that uses variable width fonts, the program should know about English grammar and render the wider space itself on any whitespace. (LaTeX is about the only thing that gets it right though). Hmm, you just gave a rule specifically for fixed-width fonts, and now you're tacitly assuming that it applies to variable-width fonts as well? (If this is wrong, blame the secretary I just asked :) There are certainly a lot of professionally-typeset books and magazines out there that don't use extra space between sentences. It's not universal, however. Some do, and some don't. My impression is that the majority of professionally-typeset material does not use extra space. I'm not sure how useful a rule is, regardless of its authority, if most of the people who ought to know enough to follow it choose not to do so. Shall we rigorously avoid splitting infinitives, as well? (That's sort of a cheap shot, since IIRC recent editions of Strunk White no longer argue against split infinitives, but then again, that rule was dropped because it was so commonly violated, not because the community of professional grammarians changed their mind about it.) Craig
Re: description writing guide
On 04 Dec 2002 19:19:38 + Scott James Remnant [EMAIL PROTECTED] wrote: In correct English grammar and typography the space after a full stop (period in Merkin) is supposed to be a wider space then that between words and after commas and suchlike. Ahh, allright, so there's still reason to be using them, at least in fixed-width fonts. I personally, though, suggest we just do away with it :) pgpzq11f5gZjV.pgp Description: PGP signature
Re: description writing guide
On Wed, 4 Dec 2002 11:33:35 -0800 Craig Dickson [EMAIL PROTECTED] wrote: I don't see any reason why package descriptions shouldn't be presented in variable-width fonts. The right margin might look a bit ragged (assuming the program preserves line breaks, which is probably a good idea to avoid messing up bulletted lists in the description), but so what? Package descriptions don't usually include tabular data that would be seriously messed up by variable-width fonts. Just for looks, and to allow some flexibility on the part of the description writer. If variable-width fonts are used, then line breaks shouldn't be preserved. If they're not going to be preserved, there needs to be a very specific set of rules as to how lines are joined. These already exist in code, actually; I believe packages.debian.org joins lines. pgpgVk65NIWMv.pgp Description: PGP signature
Re: description writing guide
On Wed, 2002-12-04 at 19:48, Craig Dickson wrote: Scott James Remnant wrote: In correct English grammar and typography the space after a full stop (period in Merkin) is supposed to be a wider space then that between words and after commas and suchlike. Hmm, you just gave a rule specifically for fixed-width fonts, and now you're tacitly assuming that it applies to variable-width fonts as well? No, I gave a rule for any English sentence. Extra space was not intend to mean the same as two fixed-width space characters. Apologies for the confusion. Scott -- Scott James Remnant Have you ever, ever felt like this? Had strange http://netsplit.com/ things happen? Are you going round the twist? signature.asc Description: This is a digitally signed message part
Re: description writing guide
On 04-Dec-02, 13:01 (CST), David B Harris [EMAIL PROTECTED] wrote: Also, in the description template, two spaces are used after a period - is that standard nowadays? (Yes, I've read some of the other responses to this.) In standard typography, it is to have extra space after a period ending a sentence. For fixed-width fonts, this often shows up as two spaces, as is fairly ugly. For variable width fonts, it's often very subtle, especially as if the text is also justified, which has a strong effect on spacing. However, this is all on *output* (display, whatever). The input text should have just a single space. The text has to be reformatted to fit the screen (display area) anyway (even on a terminal), and it's the job of the reformatter/text renderer/whatever to get it right. In practice, of course, most of the common text-based package display programs (aptitude, apt-cache show) will not bother to attempt to figure out which periods end a sentence, and thus need extra spacing. OTOH a lot of people (IMO) would argue that the fixed-width two-space end of sentence is sufficiently ugly that we're better off without it. Steve -- Steve Greenland The irony is that Bill Gates claims to be making a stable operating system and Linus Torvalds claims to be trying to take over the world. -- seen on the net
Re: description writing guide
Craig Dickson writes: Hmm, you just gave a rule specifically for fixed-width fonts, and now you're tacitly assuming that it applies to variable-width fonts as well? You are supposed to use an n-space between words and an m-space between sentences when typesetting. Using two spaces with fixed-width typefaces is an attempt to approximate that. -- John Hasler [EMAIL PROTECTED] Dancing Horse Hill Elmwood, Wisconsin
Re: description writing guide
On Wed, Dec 04, 2002 at 07:19:38PM +, Scott James Remnant wrote: If you are writing text in something that uses variable width fonts, the program should know about English grammar and render the wider space itself on any whitespace. (LaTeX is about the only thing that gets it right though). *roff also does, provided that you start each sentence on a new line (to allow it to distinguish between full stops for abbreviations and full stops at the end of sentences). Thus it's good style for man pages to be written like this rather than wrapping the start of one sentence onto the same line as the end of the last: There are several common reasons why whatis parsing fails. Sometimes authors of manual pages replace \(oq.SH NAME\(cq with \(oq.SH MYPROGRAM\(cq, and then .B mandb cannot find the section from which to extract the information it needs. Sometimes authors include a NAME section, but place free-form text there rather than \(oqname \e\- description\(cq. However, any syntax resembling the above should be accepted. -- Colin Watson [EMAIL PROTECTED]
Re: description writing guide
On Wed, 2002-12-04 at 14:01, David B Harris wrote: I do have some differences of opinion, though. It's sad, but there are a getting to be a fairly large number of DDs who are attention grabbers. Just a few days ago, I saw a package description that said something along the lines of this is the best package for this purpose ... and it certainly wasn't. Even if it was, I think everybody would agree that that kind of language doesn't belong in a Debian package description. I would tend to agree; however, I don't think that more people will say stuff like this is the best package even if we treat descriptions as a form of advertising, simply because saying this is the best isn't an effective advertisement. I think it doesn't have a strong effect on people, because it doesn't say very much. At least, advertisements I see around me don't use that kind of language. Then again though, I'm not a marketing department :) Also, I'm not sure I agree with the third paragraph; everything in it is factual and well-said, but it'd be nice if somebody who *didn't* know what GTK+ and RAD are could know conclusively, this is not what I want. When you're looking for something specific, but don't know the exact package name, the process of elimination is the best start. I know I, *personally*, have installed packages which I couldn't immediately rule out from the package description because I didn't *quite* understand the jargon. Yeah; there's no one hard and fast rule for which acronyms one should expand in the description; you just have to think about it a bit and then go with what one thinks is right. glade is a bad example for my point, though, because it has a great description :) Yeah. In paragraph five (So how can we better target these users?), I'd s/minimum/appropriate amount/. I've seen bloody jihads in very well-known projects to give only the minimum of technical jargon, and people invariably take it to far. Had they just stressed appropriateness of the text to the audience, things would have been much more reasonable. Mmm...OK, I changed it to a minimal amount of, which doesn't imply it has to be the absolute minimum, just small. In paragraph six, (So far we've mainly discussed the synopsis line), I'd s/competition/alternatives/; s/advertisement/good documentation/. (BTW, if you totally disagree with me about this advertisement stuff, do replace all references to advertisements with good advertisements and whatnot :) Done. Also, in the description template, two spaces are used after a period - is that standard nowadays? I think this is an unresolved issue. I've added a section on this to the description writing guide.
Re: description writing guide
On Wed, Dec 04, 2002 at 05:30:39PM -0500, Colin Walters [EMAIL PROTECTED] was heard to say: On Wed, 2002-12-04 at 14:01, David B Harris wrote: I do have some differences of opinion, though. It's sad, but there are a getting to be a fairly large number of DDs who are attention grabbers. Just a few days ago, I saw a package description that said something along the lines of this is the best package for this purpose ... and it certainly wasn't. Even if it was, I think everybody would agree that that kind of language doesn't belong in a Debian package description. I would tend to agree; however, I don't think that more people will say stuff like this is the best package even if we treat descriptions as a form of advertising, simply because saying this is the best isn't an effective advertisement. I think it doesn't have a strong effect on people, because it doesn't say very much. At least, advertisements I see around me don't use that kind of language. Then again though, I'm not a marketing department :) That might be true, but I would like to see language such as best package for foo explicitly deprecated in the guide. I've even written such stuff myself, back before I realized what the problems were. (hopefully there isn't anything like that left in my packages :) ) Also, in the description template, two spaces are used after a period - is that standard nowadays? I think this is an unresolved issue. I've added a section on this to the description writing guide. On an unrelated topic, it would be nice if the description format allowed whitespace to be collapsed/expanded on wordwrapped lines. The last time I checked, it seemed to at least imply that whitespace was sancrosact, and I found several packages that relied on this in their description. (sorry, I don't remember which) Daniel -- / Daniel Burrows [EMAIL PROTECTED] ---\ | Genius may have its limitations, | | but stupidity is not thus handicapped.| \--- (if (not (understand-this)) (go-to http://www.schemers.org)) /
Re: description writing guide
On Wed, Dec 04, 2002 at 12:55:50PM -0500, Colin Walters [EMAIL PROTECTED] was heard to say: I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to comment on new package descriptions, but I finally sat down and committed my thoughts on description writing in a semi-coherent form: http://people.debian.org/~walters/descriptions.html Ooh, goody :) Does this mean #45943 will finally be fixed? Daniel -- / Daniel Burrows [EMAIL PROTECTED] ---\ | Is it too late to extricate myself | | from this plot line? | | Yes. -- Fluble| \-- Does your computer have Super Cow Powers? --- http://www.debian.org --/
Re: description writing guide
On Wed, 2002-12-04 at 18:58, Daniel Burrows wrote: On Wed, Dec 04, 2002 at 12:55:50PM -0500, Colin Walters [EMAIL PROTECTED] was heard to say: I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to comment on new package descriptions, but I finally sat down and committed my thoughts on description writing in a semi-coherent form: http://people.debian.org/~walters/descriptions.html Ooh, goody :) Does this mean #45943 will finally be fixed? Well, we obviously can't force anyone to do anything; but I hope that having the reasoning more clearly laid out will motivate people...
Re: description writing guide
On Wed, 2002-12-04 at 18:55, Daniel Burrows wrote: That might be true, but I would like to see language such as best package for foo explicitly deprecated in the guide. I've even written such stuff myself, back before I realized what the problems were. (hopefully there isn't anything like that left in my packages :) ) Ok, done. On an unrelated topic, it would be nice if the description format allowed whitespace to be collapsed/expanded on wordwrapped lines. The last time I checked, it seemed to at least imply that whitespace was sancrosact, and I found several packages that relied on this in their description. (sorry, I don't remember which) I think this is hard to without switching to a format which allows us to include more metadata (like XML). So we can explicitly use stuff like ul and li for lists, instead of relying on ASCII renderings. That way we can safely word-wrap the description, instead of just treating it as the equivalent of pre.
Re: description writing guide
Colin, http://people.debian.org/~walters/descriptions.html Well, I'm not sure there should be a template -- people will use it (and thus try to squeeze information into it). I usually tell my sponsees that a description should answer the following questions, roughly in that order: - What does it do (in nontechnical terms)? - Do I need it? (look at the last sentence in the Linux Configure.help descriptions -- they're really helpful if you don't want to understand stuff because you don't need it but need to pick a choice now) - What are outstanding features and deficiencies compared to other packages (if you need X, use Y instead)? - Is this package related to other packages in some way that is not handled by the package manager (this is the client to the foo server)? I try to keep all descriptions novice friendly -- after all, it allows them to learn stuff by installing and trying out. Simon -- GPG Fingerprint: 040E B5F7 84F1 4FBC CEAD ADC6 18A0 CC8D 5706 A4B4 pgppyPiXdXeEr.pgp Description: PGP signature
Re: description writing guide
On Wed, Dec 04, 2002 at 08:05:43PM -0500, Colin Walters [EMAIL PROTECTED] was heard to say: On an unrelated topic, it would be nice if the description format allowed whitespace to be collapsed/expanded on wordwrapped lines. The last time I checked, it seemed to at least imply that whitespace was sancrosact, and I found several packages that relied on this in their description. (sorry, I don't remember which) I think this is hard to without switching to a format which allows us to include more metadata (like XML). So we can explicitly use stuff like ul and li for lists, instead of relying on ASCII renderings. That way we can safely word-wrap the description, instead of just treating it as the equivalent of pre. Descriptions are already word-wrapped (or at least they should be, not every frontend does). You can get preformatted lines (eg, for bulleted lists) by adding an extra space character at the start of the line in question. On the other hand, a proper markup language would be nice. Daniel -- / Daniel Burrows [EMAIL PROTECTED] ---\ | Somewhere, just out of sight, the unicorns are gathering. | \-- A duck! -- http://www.python.org -/
Re: description writing guide
Daniel Burrows writes: On the other hand, a proper markup language would be nice. I would be appalled were such a thing to be required. -- John Hasler [EMAIL PROTECTED] Dancing Horse Hill Elmwood, Wisconsin
Re: description writing guide
Ari Pollak wrote: I think the real issue here isn't so much actual package descriptions, but the ITPs. Most package descriptions I've seen have been pretty accurate, and tend to change a lot between the time of the ITP and actual package release. I disagree. Every time I look at the descriptions of a dozen new packages in the archive, I can file at least half a dozen bug reports, if I find the time (I've filed several hundred so far). Package descriptions tend to continue to suck. -- see shy jo pgpQwJkRiAb3P.pgp Description: PGP signature
Re: description writing guide
Colin Walters wrote: I think the package descriptions are a very important product of this project. They're going to be one of the first things people see when they use Debian, and their quality directly reflects on the quality of Debian. I've been putting in some random efforts here and there to comment on new package descriptions, but I finally sat down and committed my thoughts on description writing in a semi-coherent form: http://people.debian.org/~walters/descriptions.html Your emphasis on audiences is very good, but I am leery of the treatment of package descriptions as advertisements. A package description that reads like an in-your-face advertisement can suck at being a package description. You're right in some ways about the correspondance, but I think the thing you leave out is that these are advertisements that are aimed at getting only the users who should install a package to install it, not all users, and that if the advertisement gets accross to someone that this is probably not the package they want, it is also doing its job. Particularly if it helps them find the package they _do_ want. These are not features of traditional commercial advertisements. Insert some mumbling about zero-sum games here. The easiest problem to point to WRT description-as-advertisement is it encourages the insertation of useless superlatives into the description, as you do in the example template when you say foo is a powerful... Look at the uses of powerful in existing descriptions, for example, and see how many you agree with: kernel-image-*: lilo is characterised as a powerful bootloader python2.2-numeric: powerful multi-dimensional array objects tcl8.4: tcl is .. powerful ilisp-doc: ILISP is a powerful GNU Emacs interface teapop: Powerful and flexible snd-dmotif: powerful sound file editor wu-ftpd-academ: a powerful and widely used FTP server angband: Sauron [...] most powerful of his servants clara: features a powerful GUI mc: A powerful file manager. ncps: much more powerful than gitps libxpa-dev: a powerful tool latte: Latte is a simple and powerful language python-pygresql: easy use of the powerful PostgreSQL features srecord: collection of powerful tools phpnuke: a powerful assembly of tools clamav: Powerful antivirus scanner libgnomedb0-common: adds, to the already powerful GDA architecture lurker: with a powerful search engine zircon: Powerful X Internet Relay Chat client pspp: powerful program for statistical analysis motor-fribidi: a powerful editor ne: an easy-to-use and powerful editor gentoo: features a fairly complex and powerful file identification system dacode: Powerful and full-featured news engine Er, that's the first 10% of them; enough already. I'm left with the impression that powerful has essentially null meaning in most of these package descriptions, except perhaps when describing Sauron. I'd rather that our descriptions were more objective and weren't afraid to say hey, if you're looking for a really good foo and don't have specialized needs x y and z, you probably want bar instead. -- see shy tcl is .. powerful jo pgpqSuwGqm2ri.pgp Description: PGP signature
Re: description writing guide
On Wed, Dec 04, 2002 at 07:49:04PM -0600, John Hasler [EMAIL PROTECTED] was heard to say: Daniel Burrows writes: On the other hand, a proper markup language would be nice. I would be appalled were such a thing to be required. I didn't say I thought it was politically possible to do this, did I? Daniel -- / Daniel Burrows [EMAIL PROTECTED] ---\ |Debian developers have many superpowers, but| | time travel is not one of them.| | -- Richard Braakman | \--- (if (not (understand-this)) (go-to http://www.schemers.org)) /
