[The previous message went to [EMAIL PROTECTED] by mistake, rather than the individual bug. However, since I happened to see it as a result, I'll reply ...]
On Fri, Feb 04, 2005 at 10:55:32AM -0500, David A. Desrosiers wrote: > Dan Jacobson wrote: > > Package: pilot-link > > Version: 0.11.8-10 > > Severity: minor > > File: /usr/share/man/man1/read-notepad.1.gz > > > > The NAME field is overloaded, messing up e.g., apropos(1). > > Also don't mention install-expenses. > > "NAME" is a perfectly valid nroff keyword (see > 'man/man1/ls.1.gz' or 'man/man1/gcc.1.gz' for two good examples of > this usage. "NAME" isn't an nroff keyword in any particularly meaningful sense; about the closest nroff has to keywords are "requests" like .ft and .ig. In fact, "NAME" isn't interpreted by nroff itself except as a perfectly normal string of characters. "NAME" is a conventional string used in .SH headers in man pages (or .Sh, when using groff_mdoc(7)) to indicate the name and short description that whatis(1) and apropos(1) should display about each man page. > read-notepad will still contain the "NAME" keyword, as per the > manpage and nroff specification. We are now generating manpages from > XML sources via docbook transformation. If this is a bug in the nroff > output, the bug must be filed there. The existence of the NAME section in read-notepad(1) is correct, and I don't think there's anything wrong with the way it was converted from DocBook. However, its contents are unconventional for a NAME section; in order to produce good whatis(1) and apropos(1) output, those sections should consist of the program's name, "\-", and a one-line description of the program. At present, 'whatis read-notepad' looks like this: read-notepad (1) - Connect to the Palm handheld and list the record information found in the Palm Notepad application (found on OS4 and newer devices). Alternately, if no options are given, each record's image will be converted to files, using Portable Network Graphic (.png) or Portable Pixmap (.ppm) format. The default type is ppm. Viewed on a traditional 80-column terminal, this is suboptimal. Conventional output is more like this: man (1) - an interface to the on-line reference manuals I suggest that read-notepad's NAME section should read something like this when formatted into nroff: \fBread\-notepad\fR \- read information from the Palm Notepad application ... and that the more extended description of its behaviour currently found in the NAME section should be moved to the DESCRIPTION section. Cheers, -- Colin Watson [EMAIL PROTECTED] Debian groff and man-db maintainer -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
