Update the mdoc NTP documentation transcribed from the HTML documentation

for ntp-4.1.0.

Unfortunately, David Mills insists on managing the documentation in
such a way as to make it impossible for me to make things easy on our
translators, without printing out the documentation and reading through
it side-by-side with a finger on each page.

1 files changed, 181 insertions, 148 deletions

diff --git a/usr.sbin/ntp/doc/ntpdate.8 b/usr.sbin/ntp/doc/ntpdate.8
index f20ad896f..5c50590 100644
--- a/usr.sbin/ntp/doc/ntpdate.8
+++ b/usr.sbin/ntp/doc/ntpdate.8
@@ -9,163 +9,117 @@
 .Nd set the date and time via NTP
 .Sh SYNOPSIS
 .Nm
-.Op Fl bBdqsuv
+.Op Fl bBdoqsuv
 .Op Fl a Ar key
 .Op Fl e Ar authdelay
 .Op Fl k Ar keyfile
 .Op Fl o Ar version
 .Op Fl p Ar samples
 .Op Fl t Ar timeout
-.Ar server
-.Op Ar ...
+.Ar server ...
 .Sh DESCRIPTION
-.Nm
-sets the local date and time by polling the Network Time Protocol (NTP)
-server(s) given as the
-.Ar server
-arguments to determine
-the correct time.  It must be run as root on the local host.  A number
-of samples are obtained from each of the servers specified
-and a subset of the NTP clock filter and selection algorithms
-are applied to select the best of these.
-Note that the accuracy and reliability of
-.Nm
-depends on the number of servers,
-the number of polls each time it is run
-and the interval between runs.
 .Pp
-.Nm
-can be run manually as necessary to set the host clock,
-or it can be run from the host startup script
-to set the clock at boot time.
-This is useful in some cases to set the clock initially
-before starting the NTP daemon
-.Xr ntpd 8 .
-It is also possible to run
-.Nm
-from a
-.Xr cron 8
-script.
-However, it is important to note that
-.Nm
-with contrived cron scripts is no substitute for the NTP daemon,
-which uses sophisticated algorithms to maximize accuracy and reliability
-while minimizing resource use.
-Finally, since
-.Nm
-does not discipline the host clock frequency as does
-.Xr ntpd 8 ,
-the accuracy using
-.Nm
-is limited.
-.Pp
-Time adjustments are made by
-.Nm
-in one of two ways.  If
-.Nm
-determines the clock is in error more than 0.5 second it will simply
-step the time by calling the system
-.Xr settimeofday 2
-routine.
-If the error is less than 0.5 seconds, it will slew the time
-by calling the system
-.Xr adjtime 2
-routine.
-The latter technique is less disruptive and more
-accurate when the error is small, and works quite well when
-.Nm
-is run by
-.Xr cron 8
-every hour or two.
-.Pp
-.Nm
-will decline to set the date if an NTP server daemon
-(e.g.,
-.Xr ntpd 8 )
-is running on the same host.
-When running
-.Nm
-on a regular basis from
-.Xr cron 8
-as an alternative to running a daemon,
-doing so once every hour or two
-will result in precise enough timekeeping
-to avoid stepping the clock.
+.Em Note :
+The functionality of this program is now available
+in the
+.Xr ntpd 8   
+program.
+See the
+.Fl q   
+command line
+option in the
+.Xr ntpd 8   
+page.
+After a suitable period of
+mourning, the
+.Nm   
+program is to be retired from this
+distribution.
 .Pp
-If NetInfo support is compiled into
-.Nm ,
-then the server argument is optional if
-.Nm
-can find a time server in the NetInfo configuration for
-.Xr ntpd 8 .
+.Nm   
+sets the local date and time by polling the
+Network Time Protocol (NTP) server(s) given as the
+.Ar server
+arguments to determine the correct time.
+It must be run as root on
+the local host.
+A number of samples are obtained from each of the
+servers specified and a subset of the NTP clock filter and
+selection algorithms are applied to select the best of these.
+Note
+that the accuracy and reliability of
+.Nm   
+depends on
+the number of servers, the number of polls each time it is run and
+the interval between runs.
 .Pp
 The following options are available:
 .Bl -tag -width indent
 .It Fl a Ar key
-Enable the authentication function
-and specify the key identifier to be used
-for authentication as the argument
-.Ar key .
+Enable the authentication function and specify the key
+identifier to be used for authentication as the argument
+.Ar key
 The keys and key identifiers must match
 in both the client and server key files.
-The default is to disable the authentication function.
+The default is to disable
+the authentication function.
 .It Fl B
 Force the time to always be slewed using the
 .Xr adjtime 2
-system call,
-even if the measured offset is greater than +-128 ms.
-The default is to step the time using
+system
+call, even if the measured offset is greater than +-128 ms.
+The
+default is to step the time using
 .Xr settimeofday 2
-if the offset is greater than +-128 ms.
-Note that,
-if the offset is much greater than +-128 ms in this case,
-it can take a long time (hours)
-to slew the clock to the correct value.
-During this time,
-the host should not be used to synchronize clients.
+if the offset is
+greater than +-128 ms.
+Note that, if the offset is much greater
+than +-128 ms in this case, that it can take a long time (hours) to
+slew the clock to the correct value.
+During this time. the host
+should not be used to synchronize clients.
 .It Fl b
 Force the time to be stepped using the
 .Xr settimeofday 2
-system call,
-rather than slewed (default) using the
+system
+call, rather than slewed (default) using the
 .Xr adjtime 2
 system call.
-This option should be used
-when called from a startup file at boot time.
+This option should be used when called from a startup file at boot
+time.
 .It Fl d
-Enable the debugging mode,
-in which
-.Nm
-will go through all the steps,
-but not adjust the local clock.
-Information useful for general debugging will also be printed.
+Enable the debugging mode, in which
+.Nm   
+will go
+through all the steps, but not adjust the local clock.
+Information
+useful for general debugging will also be printed.
 .It Fl e Ar authdelay
-Specify the processing delay
-to perform an authentication function as the value
+Specify the processing delay to perform an authentication
+function as the value
 .Ar authdelay ,
 in seconds and fraction
 (see
-.Xr ntpd 8
+.Xr ntpd 8   
 for details).
-This number is usually small enough
-to be negligible for most purposes,
-though specifying a value
-may improve timekeeping on very slow CPU's.
+This number is usually small
+enough to be negligible for most purposes, though specifying a
+value may improve timekeeping on very slow CPU's.
 .It Fl k Ar keyfile
-Specify the path for the authentication key file
-as the string
+Specify the path for the authentication key file as the string
 .Ar keyfile .
 The default is
 .Pa /etc/ntp.keys .
-This file should be in the format described in
-.Xr ntpd 8 .
+This file
+should be in the format described in
+.Xr ntpd 8  . 
 .It Fl o Ar version
-Specify the NTP version for outgoing packets as the integer
+Specify the NTP version for outgoint packets as the integer
 .Ar version ,
 which can be 1 or 2.
 The default is 3.
 This allows
-.Nm
+.Nm   
 to be used with older NTP versions.
 .It Fl p Ar samples
 Specify the number of samples to be acquired from each server
@@ -176,37 +130,121 @@ The default is 4.
 .It Fl q
 Query only - don't set the clock.
 .It Fl s
-Divert logging output from the standard output (default)
-to the system
-.Xr syslog 3
+Divert logging output from the standard output (default) to the
+system
+.Xr syslog 3   
 facility.
-This is designed primarily for convenience of
-.Xr cron 8
+This is designed primarily for
+convenience of
+.Xr cron 8   
 scripts.
 .It Fl t Ar timeout
-Specify the maximum time waiting for a server response
-as the value
+Specify the maximum time waiting for a server response as the
+value
 .Ar timeout ,
 in seconds and fraction.
-The value is rounded to a multiple of 0.2 seconds.
-The default is 1 second,
-a value suitable for polling across a LAN.
+The value is is
+rounded to a multiple of 0.2 seconds.
+The default is 1 second, a
+value suitable for polling across a LAN.
 .It Fl u
 Direct
-.Nm
-to use an unprivileged port for outgoing packets.
-This is most useful when behind a firewall
-that blocks incoming traffic to privileged ports,
-and you want to synchronise with hosts beyond the firewall.
+.Nm   
+to use an unprivileged port or outgoing
+packets.
+This is most useful when behind a firewall that blocks
+incoming traffic to privileged ports, and you want to synchronise
+with hosts beyond the firewall.
 Note that the
-.Fl d
-option always uses unprivileged ports.
+.Fl d   
+option
+always uses unprivileged ports.
 .It Fl v
 Be verbose.
 This option will cause
 .Nm Ns 's
-version identification string to be logged.
+version
+identification string to be logged.
 .El
+.Pp
+.Nm   
+can be run manually as necessary to set the
+host clock, or it can be run from the host startup script to set
+the clock at boot time.
+This is useful in some cases to set the
+clock initially before starting the NTP daemon
+.Xr ntpd 8  . 
+It is
+also possible to run
+.Nm   
+from a
+.Xr cron 8   
+script.
+However, it is important to note that
+.Nm   
+with
+contrived
+.Xr cron 8   
+scripts is no substitute for the NTP
+daemon, which uses sophisticated algorithms to maximize accuracy
+and reliability while minimizing resource use.
+Finally, since
+.Nm   
+does not discipline the host clock frequency as
+does
+.Xr ntpd 8  , 
+the accuracy using
+.Nm   
+is
+limited.
+.Pp
+Time adjustments are made by
+.Nm   
+in one of two
+ways.
+If
+.Nm   
+determines the clock is in error more
+than 0.5 second it will simply step the time by calling the system
+.Xr settimeofday 2
+routine.
+If the error is less than 0.5
+seconds, it will slew the time by calling the system
+.Xr adjtime 2
+routine.
+The latter technique is less disruptive
+and more accurate when the error is small, and works quite well
+when
+.Nm   
+is run by
+.Xr cron 8   
+every hour or
+two.
+.Pp
+.Nm   
+will decline to set the date if an NTP server
+daemon (e.g.,
+.Xr ntpd 8 )  
+is running on the same host.
+When
+running
+.Nm   
+on a regular basis from
+.Xr cron 8   
+as
+an alternative to running a daemon, doing so once every hour or two
+will result in precise enough timekeeping to avoid stepping the
+clock.
+.Pp
+If NetInfo support is compiled into
+.Nm , 
+then the
+.Ic server   
+argument is optional if
+.Nm   
+can find a
+time server in the NetInfo configuration for
+.Xr ntpd 8  . 
 .Sh FILES
 .Bl -tag -width /etc/ntp.keys -compact
 .It Pa /etc/ntp.keys
@@ -215,17 +253,12 @@ contains the encryption keys used by
 .El
 .Sh SEE ALSO
 .Xr ntpd 8
-.Sh HISTORY
-Written by
-.An Dennis Ferguson
-at the University of Toronto
 .Sh BUGS
-The slew adjustment is actually 50% larger than the measured offset,
-since this (it is argued)
-will tend to keep a badly drifting clock more accurate.
-This is probably not a good idea
-and may cause a troubling hunt
-for some values of the kernel variables
-.Va tick
+The slew adjustment is actually 50% larger than the measured
+offset, since this (it is argued) will tend to keep a badly
+drifting clock more accurate.
+This is probably not a good idea and
+may cause a troubling hunt for some values of the kernel variables
+.Va kern.clockrate.tick
 and
-.Va tickadj .
+.Va kern.clockrate.tickadj .