From owner-svn-src-all@FreeBSD.ORG Fri Mar 9 05:14:59 2012 Return-Path: Delivered-To: svn-src-all@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 6454A1065672; Fri, 9 Mar 2012 05:14:59 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail05.syd.optusnet.com.au (mail05.syd.optusnet.com.au [211.29.132.186]) by mx1.freebsd.org (Postfix) with ESMTP id 007378FC14; Fri, 9 Mar 2012 05:14:58 +0000 (UTC) Received: from c211-30-171-136.carlnfd1.nsw.optusnet.com.au (c211-30-171-136.carlnfd1.nsw.optusnet.com.au [211.30.171.136]) by mail05.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id q295EoRe009405 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Fri, 9 Mar 2012 16:14:51 +1100 Date: Fri, 9 Mar 2012 16:14:46 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Ed Maste In-Reply-To: <201203081527.q28FRUSm050522@svn.freebsd.org> Message-ID: <20120309155320.W1588@besplex.bde.org> References: <201203081527.q28FRUSm050522@svn.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: svn-src-head@FreeBSD.org, svn-src-all@FreeBSD.org, src-committers@FreeBSD.org Subject: Re: svn commit: r232695 - head/share/man/man4 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 09 Mar 2012 05:14:59 -0000 On Thu, 8 Mar 2012, Ed Maste wrote: > Log: > Correct markup, use proper reference for sysctl(3) This is sort of backwards. > Submitted by: brueffer@ > > Modified: > head/share/man/man4/tcp.4 > > Modified: head/share/man/man4/tcp.4 > ============================================================================== > --- head/share/man/man4/tcp.4 Thu Mar 8 13:00:49 2012 (r232694) > +++ head/share/man/man4/tcp.4 Thu Mar 8 15:27:29 2012 (r232695) > @@ -256,8 +256,10 @@ or the internal send buffer is filled. > This option enables the use of MD5 digests (also known as TCP-MD5) > on writes to the specified socket. > Outgoing traffic is digested; > -digests on incoming traffic are verified > -if the net.inet.tcp.signature_verify_input sysctl is nonzero. > +digests on incoming traffic are verified if the > +.Va net.inet.tcp.signature_verify_input > +.Xr sysctl 3 sysctl(3) is a man page for sysctls. The (3) in it is part of its name. It is not part of the name of any sysctl. > +is nonzero. > The current default behavior for the system is to respond to a system > advertising this option with TCP-MD5; this may change. > .Pp Normal abuse of language is "the foo sysctl". This is a to avoid writing out a full description, which would be something like "the foo feature, which is controlled in the usual way by sysctl(3) at the programmer level and by sysctl(8) at the sysadmin level". For most sysctls (_not_ for most sysctl(3)s or sysctl(8)s), their man page is not the place to reference sysctl(3) or sysctl(8). The reference to sysctl(3) is negatively useful here, as in most places: - except for a few style inconsistencies, sysctl(3) contains no documentation about any sysctl by name. It mainly documents a very incomplete set of sysctls by number. It doesn't document even 1 tcp sysctl by either name or number. - sysctl(8) mainly documents a very incomplete set of sysctls by name. However, it too doesn't document even 1 tcp sysctl. - this sysctl actually is documented, in tcp(4). But that's where we already are. It would be more useful to refer to red_herring(3), since everyone knows how much time they should spend reading that. Bruce