Bug#39830: [AMENDMENT]: get rid of undocumented(7) symlinks
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 [cjwatson@flatline.org.uk]
Reply to: