svn commit: r232695 - head/share/man/man4

[Bruce Evans]

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