docs/104493: [patch] Wrong description in ntp.conf(5) (CURRENT and 6.2-BETA2)

[Watanabe Kazuhiro]

>Number:         104493
>Category:       docs
>Synopsis:       [patch] Wrong description in ntp.conf(5) (CURRENT and 6.2-BETA2)
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Tue Oct 17 12:50:22 GMT 2006
>Closed-Date:
>Last-Modified:
>Originator:     Watanabe Kazuhiro
>Release:        FreeBSD 7.0-CURRENT i386
>Organization:
=09
>Environment:
System: FreeBSD scorpio.zodiac.org 7.0-CURRENT FreeBSD 7.0-CURRENT #26: Mon=
 Oct 16 15:11:12 JST 2006 nabe at scorpio.zodiac.org:/FreeBSD/obj-current/Free=
BSD/FreeBSD-current/src/sys/GENERIC i386

There is the same problem on 6.2-BETA2.
>Description:
In ntp.conf(5), there is a wrong description:

 allan allan
         The argument becomes the new value for the minimum Allan
         intercept, which is a parameter of the PLL/FLL clock dis-
         cipline algorithm.  The value in log2 seconds defaults to
         7 (1024 s), which is also the lower limit.

Yes.  log2(1024) is not 7, but 10.  There is also the same description
in /usr/share/doc/ntp/miscopt.html, and they have been obsoleted.

=46rom ntp-4.2.0 (currently contributed in FreeBSD) and later,
this variable "allan" is set a real number (not an exponential number)
and defaults to 1500.

The default value is defined in src/contrib/ntp/ntpd/ntp_loopfilter.c.
The old version (ntp-4.1.2) was:

 #define CLOCK_ALLAN     10      /* min Allan intercept (log2 s) */

and the recent version (ntp-4.2.0 and later) is:

 #define CLOCK_ALLAN     1500.   /* compromise Allan intercept (s) */


The description has fixed in ntp-4.2.2:

 allan allan
         The argument becomes the new value for the Allan
         intercept, which is a parameter of the PLL/FLL clock
         discipline algorithm. The value is in seconds with
         default 1500 s, which is appropriate for most computer
         clocks.
>How-To-Repeat:
man ntp.conf
>Fix:
Here is a patch for CURRENT.

--- contrib/ntp/html/miscopt.html.orig	Wed Jul 21 00:01:05 2004
+++ contrib/ntp/html/miscopt.html	Tue Oct 17 00:34:27 2006
@@ -64,7 +64,7 @@
             <p>The variables operate as follows:</p>
             <dl>
                 <dt><tt>allan <i>allan</i></tt>
-                <dd>The argument becomes the new value for the minimum All=
an intercept, which is a parameter of the PLL/FLL clock discipline algorith=
m. The value in log2 seconds defaults to 7 (1024 s), which is also the lowe=
r limit.
+                <dd>The argument becomes the new value for the Allan inter=
cept, which is a parameter of the PLL/FLL clock discipline algorithm. The v=
alue is in  seconds with default 1500 s, which is appropriate for most comp=
uter clocks.
                 <dt><tt>dispersion <i>dispersion</i></tt>
                 <dd>The argument becomes the new value for the dispersion =
increase rate, normally .000015 s/s.
                 <dt><tt>freq <i>freq</i></tt>
--- usr.sbin/ntp/doc/ntp.conf.5.orig	Mon Oct 16 11:29:06 2006
+++ usr.sbin/ntp/doc/ntp.conf.5	Tue Oct 17 00:31:48 2006
@@ -2600,11 +2600,11 @@
 The variables operate as follows:
 .Bl -tag -width indent
 .It Cm allan Ar allan
-The argument becomes the new value for the minimum Allan
+The argument becomes the new value for the Allan
 intercept, which is a parameter of the PLL/FLL clock discipline
 algorithm.
-The value in log2 seconds defaults to 7 (1024 s), which is also the lower
-limit.
+The value is in seconds with default 1500 s, which is appropriate
+for most computer clocks.
 .It Cm dispersion Ar dispersion
 The argument becomes the new value for the dispersion increase rate,
 normally .000015 s/s.
>Release-Note:
>Audit-Trail:
>Unformatted: