Date: Fri, 9 Mar 2012 16:14:46 +1100 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Ed Maste <emaste@FreeBSD.org> Cc: svn-src-head@FreeBSD.org, svn-src-all@FreeBSD.org, src-committers@FreeBSD.org Subject: Re: svn commit: r232695 - head/share/man/man4 Message-ID: <20120309155320.W1588@besplex.bde.org> In-Reply-To: <201203081527.q28FRUSm050522@svn.freebsd.org> References: <201203081527.q28FRUSm050522@svn.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120309155320.W1588>