> I'd expect the manpage to tell me about what the function is and how
> to use it.  If we want to document "wrong" usages we should be
> consistent about this everywhere,

I don't see any particular need to.  Warning about things likely to be
problematic is one of the things good documentation does; our existing
documentation is of such variable quality that I don't think we should
hold off on improving doc A because doc B isn't up to the same
standard.

/~\ The ASCII				der Mouse
\ / Ribbon Campaign
 X  Against HTML	       mouse@rodents.montreal.qc.ca
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B