cvs commit: src/usr.bin/fetch fetch.1

[Diomidis Spinellis]

Alfred Perlstein wrote:

> * Ruslan Ermilov <ru at FreeBSD.org> [040123 00:06] wrote:
> 
>>On Thu, Jan 22, 2004 at 08:50:48PM -0800, Wes Peters wrote:
>>
>>>wes         2004/01/22 20:50:48 PST
>>>
>>>  FreeBSD src repository
>>>
>>>  Modified files:
>>>    usr.bin/fetch        fetch.1 
>>>  Log:
>>>  Document fetch(1) environment variables in fetch(1) man page, instead of
>>>  taking lazy users on the arduous journey through SEE ALSO to fetch(3).
>>>  
>>>  PR:             docs/61759
>>>  Submitted by:   Christian S.J. Peron <maneo at bsdpro.com>
>>>  
>>>  Revision  Changes    Path
>>>  1.55      +108 -12   src/usr.bin/fetch/fetch.1
>>>
>>
>>Duplication is always bad.  I also think that this change wasn't
>>approved by the maintainer.
> 
> For some reason I'd rather see fetch(3) xref fetch(1) for the
> docco, it means that programmers may have to go through an extra
> step rather than users.

Let us not forget that the Unix manual pages provide reference material; 
they are not a user guide.  They historically have been terse, to the 
point, and honest in admitting shortcomings (bugs).  While a user might 
find it helpful to read the environment variable documentation in 
fetch(1), the correct thing to do in reference material is to document 
the variables where they are implemented, namely fetch(3), and provide a 
cross reference.

Diomidis - dds@