From owner-cvs-src@FreeBSD.ORG  Sat Jan 24 14:02:17 2004
Return-Path: <owner-cvs-src@FreeBSD.ORG>
Delivered-To: cvs-src@freebsd.org
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP
	id DB20316A4CE; Sat, 24 Jan 2004 14:02:17 -0800 (PST)
Received: from hermes.aueb.gr (hermes.aueb.gr [195.251.255.142])
	by mx1.FreeBSD.org (Postfix) with ESMTP
	id 16D3B43D31; Sat, 24 Jan 2004 14:02:16 -0800 (PST)
	(envelope-from dds@aueb.gr)
Received: from aueb.gr (faculty04.right.dialup.aueb.gr [195.251.255.248])
	by hermes.aueb.gr (8.12.9/8.12.9) with ESMTP id i0OM20Cd029527;
	Sun, 25 Jan 2004 00:02:00 +0200
Message-ID: <40123A86.3040102@aueb.gr>
Date: Sat, 24 Jan 2004 11:27:34 +0200
From: Diomidis Spinellis <dds@aueb.gr>
User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US;
	rv:1.5) Gecko/20031007
X-Accept-Language: en-us, en, el, de
MIME-Version: 1.0
To: Alfred Perlstein <alfred@FreeBSD.org>
References: <200401230450.i0N4omSZ049990@repoman.freebsd.org>
	<20040123080657.GC34542@FreeBSD.org.ua> <20040123102933.GC53344@elvis.mu.org>
In-Reply-To: <20040123102933.GC53344@elvis.mu.org>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
cc: src-committers@FreeBSD.org
cc: Ruslan Ermilov <ru@FreeBSD.org>
cc: Wes Peters <wes@FreeBSD.org>
cc: cvs-src@FreeBSD.org
cc: cvs-all@FreeBSD.org
cc: Dag-Erling Smorgrav <des@FreeBSD.org>
Subject: Re: cvs commit: src/usr.bin/fetch fetch.1
X-BeenThere: cvs-src@freebsd.org
X-Mailman-Version: 2.1.1
Precedence: list
List-Id: CVS commit messages for the src tree <cvs-src.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-src>,
	<mailto:cvs-src-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/cvs-src>
List-Post: <mailto:cvs-src@freebsd.org>
List-Help: <mailto:cvs-src-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/cvs-src>,
	<mailto:cvs-src-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Sat, 24 Jan 2004 22:02:18 -0000

Alfred Perlstein wrote:

> * Ruslan Ermilov <ru@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@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@