Re: Bug#39830: debian-policy: [PROPOSED]: get rid of undocumented(7) symlinks

[Chris Waters <xtifr@dsp.net>]

Chris Lawrence <quango@watervalley.net> writes:

> I would be willing to support this proposal with the following
> additional sentence included:

> "It is not very hard to write a manual page; see the example manual
> page provided by dh_make for a template."

I disagree (mildly).  Policy should state policy, not provide
editorial and advice.  A statement like this would be more appropriate
in the Packaging Manual.  In Policy, it could be mistaken for an
official requirement to use dh_make (bleah:), or something like that.

And in any case, the statement "it is not hard to write a manual page"
is misleading.  It may not be a *technical* challenge, but it may
provide other challenges for those whose first language is not
English.  Or for those (like me) who suffer from occasional bouts of
perfectionism, and can agonize for days over a single sentence. :-)

It may be easy to write a useless man page, but not always so easy to
write a useful one.  And I'd almost rather have no man page than a
useless one -- in fact, that's kind of the whole point of this proposal.

But in any case, even granting that it's not hard, that's still not a
matter of policy.  It's merely a fact.

I think that the old policy of using undocumented(7) made it too easy
for people to ignore the requirement to have a *real* man page, and I
think this proposal (without editorial commentary) will go a long way
toward addressing that issue, since undocumented(7) will no longer
have the dubious blessing of being mentioned in policy.
-- 
Chris Waters   xtifr@dsp.net | I have a truly elegant proof of the
      or    xtifr@debian.org | above, but it is too long to fit into
http://www.dsp.net/xtifr     | this .signature file.