code vs. documentation : which to change?

[Tony Birnseth]

When a program doesn't behave like the manual says, how do you decide 
which to change?


Case in point: In the Aug. 1983 edition of the 4.2bsd UNIX Programmer's
Manual, the man page for csh(1) says at one point:

	A history reference may be given without an event
	specification, e.g. '!$'.  In this case the reference
	is to the previous command unless a previous history
	reference occurred on the same line in which case this
	form repeats the previous reference.  Thus '!?foo?^ !$'
	gives the first and last arguments from the command
	matching '?foo?'.

Well, csh doesn't do the ?foo? part that way.  Specifically, the
history reference is always relative to the current command line, whether
multiple history references occur on one line or not (for changes to
csh that make it behave like the paragraph states, see net.bugs.4bsd,
under the title "csh history bug (with fix)").


We as a support group are caught in a double bind.  On one hand, 
we want to provide our users with utilities that are as bug-free,
and useful as possible.  On the other hand, our users develop production 
software to run at other sites.  We want users to have a 'vanilla' 
Berkeley system so their code will run elsewhere.  The main way we 
accomplish this is to make 'sugared' and non-Berkeley commands live 
in a local directory, and let the user define their environment by
the way they set their PATH variable.

I can't seem to find a case where the manual declared some functionality
and we changed the documentation to reflect the non-functional code.
In contrast, there have been numerous cases where un-documented features 
were found in the code, and the manuals were changed to reflect its 
functionality.

Csh(1) has far greater impact than other programs.  Bugs have almost 
become standard functionality.  I do not want to support 2 versions of the 
C-shell.  Before I implement this change, I'd like your thoughts on the
following:
	How would you handle this (csh) problem specifically.
	How do you handle this kind of problem in general?
	How do you tell when a bugfix actually makes a command non-standard?
	How do you decide whether to change the code or the documentation?


Please help unload the net and send replies directly to me.  If response 
warrents, I will summarize in human readable form at a later date.

Tony Birnseth				
===============================================================================
|	   Real			|		Virtual			      |
|	   ----			|		------- 		      |
| Small Systems Support Group	|					      |
| Computer Resource Dept.	| USENET    ../{ucbvax,decvax}!tektronix!tonyb|
| Tektronix Inc. 19-333		| CSNET     tonyb at tektronix.csnet	      |
| P.O. Box 500			| ARPAnet   tonyb%tektronix at csnet-relay.ARPA  |
| Beaverton, Or. 97077		| Ma Bell - (503) 627-5394		      |
===============================================================================