On Tue, Nov 12, 2002 at 05:27:50PM +0100, Josip Rodin wrote: > On Tue, Nov 12, 2002 at 12:53:35PM +0000, Colin Watson wrote: > > + There should be a manual page at least for every program. If > > + no manual page is available, this is considered as a bug and > > + should be reported to the Debian Bug Tracking System (the > > + maintainer of the package is allowed to write this bug report > > + himself, too). Do not close the bug report until a proper > > + manpage is available.<footnote> > > This wording is unclear, it could be misinterpreted by newbie maintainers to > mean no manual page at all in the package, as opposed to no manual page per > each shipped program. Yeah, I know, I'm nitpicking. :)
"No manual page" is just an abbreviation for what's in the previous sentence. But I don't mind if a policy editor wants to clarify the wording. > Note that I don't want to second this proposal even if you fix the above, > because I think the undocumented(7) manual page is better than nothing for > total newbies. Sorry. :) > > (Thanks for not outlawing it -- then I'd have to object.) The undocumented(7) page itself can continue to exist. As discussed on IRC, I'm happy to hack man-db so that it can (configurably) point to further information in addition to the "No manual entry for foo" message. The reason why I'm supporting this proposal is because I find the symlinks to undocumented(7) technically less than ideal in a number of ways. They lead to a farm of dangling symlinks on machines that don't have the manpages package installed (#32019, #53214); they have translation issues that would necessitate some very ugly hacks like not honouring symlinks in the expected way (#167291); and they cause this very common complaint due to the symlinks showing up in 'dpkg -L' output: 17:06 <weasel> you are happy that you finally found some docs, wait for groff to render it, and what you get is a stupid undocumented(7) page Indeed it is useful to have better-than-nothing documentation for newbies, so let's arrange for the pointer to be kept in a central place, something like: No manual entry for foo. Either you mistyped, or there is no documentation for this feature: try 'man 7 undocumented'. This policy proposal, however, doesn't mandate any particular arrangement along these lines: if you'd be happy with *something* like this in place of the symlink farm then we can sort out the details as time goes on. As you correctly note, I'd simply like to drop the policy *requirement* that programs without a man page ship a symlink to undocumented(7). > > + It is not very hard to write a man page. See the <url > > + id="http://www.schweikhardt.net/man_page_howto.html"; > > + name="Man-Page-HOWTO">, <tt>man(7)</tt>, the examples > > + created by <tt>debmake</tt> or <tt>dh_make</tt>, or the > > + directory <file>/usr/share/doc/man-db/examples</file>. > > Oh, and that should be <manref name="man" section="7">. Again, I'm happy to leave it to a policy editor to fix the markup if desired. Cheers, -- Colin Watson [EMAIL PROTECTED]
