[ntpsec commit] Factor server and fudge option documentation for refclocks.

Eric S. Raymond esr at ntpsec.org
Mon Oct 12 23:00:39 UTC 2015


Module:    ntpsec
Branch:    master
Commit:    756a05edc44ccda754392bf1bab56368f8e31caf
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=756a05edc44ccda754392bf1bab56368f8e31caf

Author:    Eric S. Raymond <esr at thyrsus.com>
Date:      Mon Oct 12 19:00:31 2015 -0400

Factor server and fudge option documentation for refclocks.

---

 docs/clockopt.txt                | 68 +---------------------------------
 docs/includes/assoc-commands.txt |  2 +-
 docs/includes/assoc-options.txt  |  2 +-
 docs/includes/clock-options.txt  | 80 ++++++++++++++++++++++++++++++++++++++++
 ntpd/ntp.conf.txt                | 79 +--------------------------------------
 5 files changed, 85 insertions(+), 146 deletions(-)

diff --git a/docs/clockopt.txt b/docs/clockopt.txt
index fc5370b..7befb27 100644
--- a/docs/clockopt.txt
+++ b/docs/clockopt.txt
@@ -18,7 +18,7 @@ include::includes/clockopt.txt[]
 [[addrs]]
 == Reference Clock Adddresses ==
 
-Unless noted otherwise, further information about these ccommands is on
+Unless noted otherwise, further information about these commands is on
 the link:refclock.html[Reference Clock Support] page.
 
 Reference clocks are identified by a syntactically correct but invalid
@@ -32,71 +32,7 @@ unit numbers must be unique.
 [[cmd]]
 == Commands and Options ==
 
-`server 127.127.`'t'.'u' [`prefer`] [`mode` 'int'] [`minpoll` 'int'] [`maxpoll` 'int']::
-  This command can be used to configure reference clocks in special
-  ways. The options are interpreted as follows:
-  `prefer`;;
-    Marks the reference clock as preferred. All other things being
-    equal, this host will be chosen for synchronization among a set of
-    correctly operating hosts. See the link:prefer.html[Mitigation Rules
-    and the `prefer` Keyword] page for further information.
-  `mode` 'int';;
-    Specifies a mode number which is interpreted in a device-specific
-    fashion. For instance, it selects a dialing protocol in the ACTS
-    driver and a device subtype in the `parse` drivers.
-   `minpoll` 'int';;
-   `maxpoll` 'int';;
-    These options specify the minimum and maximum polling interval for
-    reference clock messages in log~2~ seconds. For most directly
-    connected reference clocks, both `minpoll` and `maxpoll` default to
-    6 (64 s). For modem reference clocks, `minpoll` is ordinarily set to
-    10 (about 17 m) and `maxpoll` to 15 (about 9 h). The allowable range
-    is 4 (16 s) to 17 (36 h) inclusive.
-`fudge 127.127.`'t'.'u' [`time1` 'sec'] [`time2` 'sec'] [`stratum` 'int'] [`refid` 'string'] [`flag1 0|1`] [`flag2 0|1`] [`flag3 0|1`] [`flag4 0|1`]::
-  This command can be used to configure reference clocks in special
-  ways. It must immediately follow the `server` command which configures
-  the driver. Note that the same capability is possible at run time
-  using the link:ntpq.html[`{ntpq}`] program. The options are interpreted as follows:
-  `time1` 'sec';;
-    Specifies a constant to be added to the time offset produced by the
-    driver, a fixed-point decimal number in seconds. This is used as a
-    calibration constant to adjust the nominal time offset of a
-    particular clock to agree with an external standard, such as a
-    precision PPS signal. It also provides a way to correct a systematic
-    error or bias due to serial port or operating system latencies,
-    different cable lengths or receiver internal delay. The specified
-    offset is in addition to the propagation delay provided by other
-    means, such as internal DIPswitches. Where a calibration for an
-    individual system and driver is available, an approximate correction
-    is noted in the driver documentation pages.
-    Note: in order to facilitate calibration when more than one radio
-    clock or PPS signal is supported, a special calibration feature is
-    available. It takes the form of an argument to the `enable` command
-    described in the link:miscopt.html[Miscellaneous Options] page and
-    operates as described in the link:refclock.html[Reference Clock
-    Support] page.
-  `time2` 'secs';;
-    Specifies a fixed-point decimal number in seconds, which is
-    interpreted in a driver-dependent way. See the descriptions of
-    specific drivers in the link:refclock.html[Reference Clock Support]
-    page.
-  `stratum` 'int';;
-    Specifies the stratum number assigned to the driver in the range 0
-    to 15, inclusive. This number overrides the default stratum number
-    ordinarily assigned by the driver itself, usually zero.
-  `refid` 'string';;
-    Specifies an ASCII string of from one to four characters which
-    defines the reference identifier used by the driver. This string
-    overrides the default identifier ordinarily assigned by the driver
-    itself.
-  `flag1 flag2 flag3 flag4`;;
-    These four flags are used for customizing the clock driver. The
-    interpretation of these values, and whether they are used at all, is
-    a function of the particular driver. However, by convention `flag4`
-    is used to enable recording monitoring data to the `clockstats` file
-    configured with the `filegen` command. Additional information on the
-    `filegen` command is on the link:monopt.html[Monitoring Options]
-    page.
+include::includes/clock-options.txt[]
 
 '''''
 
diff --git a/docs/includes/assoc-commands.txt b/docs/includes/assoc-commands.txt
index 9286e39..956b8be 100644
--- a/docs/includes/assoc-commands.txt
+++ b/docs/includes/assoc-commands.txt
@@ -1,6 +1,6 @@
 // Syntax and usage of association commands.  This is included
 // twice, one in generating the Web documentation tree and one when
-// generating the munual page describing the daemon config file.
+// generating the manual page describing the daemon config file.
 
 `pool` _address_ [`burst`] [`iburst`] [`version` _version_] [`prefer`] [`minpoll` _minpoll_] [`maxpoll` _maxpoll_] [`preempt`]::
 `server` _address_ [`key` _key_ | `autokey`] [`burst`] [`iburst`] [`version` _version_] [`prefer`] [`minpoll` _minpoll_] [`maxpoll` _maxpoll_]::
diff --git a/docs/includes/assoc-options.txt b/docs/includes/assoc-options.txt
index a58a048..f4fcc40 100644
--- a/docs/includes/assoc-options.txt
+++ b/docs/includes/assoc-options.txt
@@ -1,7 +1,7 @@
 // Association options - included twice.
 //
 // Note, some of these options are described with special refclock
-// semantics on the ntp.conf manual page.
+// semantics in includes/clock-options.txt.
 
 `autokey`::
   All packets sent to and received from the server or peer are to
diff --git a/docs/includes/clock-options.txt b/docs/includes/clock-options.txt
new file mode 100644
index 0000000..be5c96e
--- /dev/null
+++ b/docs/includes/clock-options.txt
@@ -0,0 +1,80 @@
+// Options for refclocks.  Included twice.
+//
+// This can't be merged with the master description of association
+// options because the cited options have different
+// and more specific semantics when used with refclocks.
+
+`server` _127.127.t_._u_ [`prefer`] [`mode` _int_] [`minpoll` _int_]
+[`maxpoll` _int_]::
+  This command can be used to configure reference clocks in special
+  ways. The options are interpreted as follows:
+
+  `prefer`;;
+    Marks the reference clock as preferred. All other things being
+    equal, this host will be chosen for synchronization among a set of
+    correctly operating hosts. See the "Mitigation Rules and the prefer
+    Keyword" page (available as part of the HTML documentation provided
+    in `/usr/share/doc/{ntp}`) for further information.
+  `mode` _int_;;
+    Specifies a mode number which is interpreted in a device-specific
+    fashion. For instance, it selects a dialing protocol in the ACTS
+    driver and a device subtype in the parse drivers.
+  `minpoll` _int_; `maxpoll` _int_;;
+    These options specify the minimum and maximum polling interval for
+    reference clock messages, as a power of 2 in seconds. For most
+    directly connected reference clocks, both _minpoll_ and _maxpoll_
+    default to 6 (64 sec). For modem reference clocks, _minpoll_ defaults
+    to 10 (17.1 min) and _maxpoll_ defaults to 14 (4.5 hours). The allowable
+    range is 4 (16 sec) to 17 (36.4 hours) inclusive.
+
+`fudge` _127.127.t_._u_ [`time1` _sec_] [`time2` _sec_] [`stratum` _int_] [`refid` _string_] [`mode` _int_] [`flag1` `0` | `1`] [`flag2` `0` | `1`] [`flag3` `0` | `1`] [`flag4` `0` | `1`]::
+  This command can be used to configure reference clocks in special
+  ways. It must immediately follow the `server` command which configures
+  the driver. Note that the same capability is possible at run time
+  using the {ntpqman} program. The options are interpreted as
+  follows:
+
+  `time1` _sec_;;
+    Specifies a constant to be added to the time offset produced by the
+    driver, a fixed-point decimal number in seconds. This is used as a
+    calibration constant to adjust the nominal time offset of a
+    particular clock to agree with an external standard, such as a
+    precision PPS signal. It also provides a way to correct a systematic
+    error or bias due to serial port or operating system latencies,
+    different cable lengths or receiver internal delay. The specified
+    offset is in addition to the propagation delay provided by other
+    means, such as internal DIPswitches. Where a calibration for an
+    individual system and driver is available, an approximate correction
+    is noted in the driver documentation pages. Note: in order to
+    facilitate calibration when more than one radio clock or PPS signal
+    is supported, a special calibration feature is available. It takes
+    the form of an argument to the `enable` command described in
+    "Miscellaneous Options" page and operates as described in the
+    "Reference Clock Drivers" page.
+  `time2` _secs_;;
+    Specifies a fixed-point decimal number in seconds, which is
+    interpreted in a driver-dependent way. See the descriptions of
+    specific drivers in the "Reference Clock Drivers" page.
+  `stratum` _int_;;
+    Specifies the stratum number assigned to the driver, an integer
+    between 0 and 15. This number overrides the default stratum number
+    ordinarily assigned by the driver itself, usually zero.
+  `refid` _string_;;
+    Specifies an ASCII string of from one to four characters which
+    defines the reference identifier used by the driver. This string
+    overrides the default identifier ordinarily assigned by the driver
+    itself.
+  `mode` _int_;;
+    Specifies a mode number which is interpreted in a device-specific
+    fashion. For instance, it selects a dialing protocol in the ACTS
+    driver and a device subtype in the parse drivers.
+  `flag1` `0` | `1`; `flag2` `0` | `1`; `flag3` `0` | `1`; `flag4` `0` | `1`;;
+    These four flags are used for customizing the clock driver. The
+    interpretation of these values, and whether they are used at all, is
+    a function of the particular clock driver. However, by convention
+    `flag4` is used to enable recording monitoring data to the
+    _clockstats_ file configured with the _filegen_ command. Further
+    information on the _filegen_ command can be found in "Monitoring
+    Options".
+
+//end
diff --git a/ntpd/ntp.conf.txt b/ntpd/ntp.conf.txt
index 374ac36..71753a9 100644
--- a/ntpd/ntp.conf.txt
+++ b/ntpd/ntp.conf.txt
@@ -235,84 +235,7 @@ documentation provided in `/usr/share/doc/{ntp}`).
 
 == Reference Clock Commands
 
-// This can't be merged with the master description of association
-// options (included above) because the cited options have different
-// and more specific semantics when used with refclocks.
-
-`server` _127.127.t_._u_ [`prefer`] [`mode` _int_] [`minpoll` _int_]
-[`maxpoll` _int_]::
-  This command can be used to configure reference clocks in special
-  ways. The options are interpreted as follows:
-
-  `prefer`;;
-    Marks the reference clock as preferred. All other things being
-    equal, this host will be chosen for synchronization among a set of
-    correctly operating hosts. See the "Mitigation Rules and the prefer
-    Keyword" page (available as part of the HTML documentation provided
-    in `/usr/share/doc/{ntp}`) for further information.
-  `mode` _int_;;
-    Specifies a mode number which is interpreted in a device-specific
-    fashion. For instance, it selects a dialing protocol in the ACTS
-    driver and a device subtype in the parse drivers.
-  `minpoll` _int_; `maxpoll` _int_;;
-    These options specify the minimum and maximum polling interval for
-    reference clock messages, as a power of 2 in seconds For most
-    directly connected reference clocks, both _minpoll_ and _maxpoll_
-    default to 6 (64 s). For modem reference clocks, _minpoll_ defaults
-    to 10 (17.1 m) and _maxpoll_ defaults to 14 (4.5 h). The allowable
-    range is 4 (16 s) to 17 (36.4 h) inclusive.
-
-`fudge` _127.127.t_._u_ [`time1` _sec_] [`time2` _sec_] [`stratum` _int_] [`refid` _string_] [`mode` _int_] [`flag1` `0` | `1`] [`flag2` `0` | `1`] [`flag3` `0` | `1`] [`flag4` `0` | `1`]::
-  This command can be used to configure reference clocks in special
-  ways. It must immediately follow the `server` command which configures
-  the driver. Note that the same capability is possible at run time
-  using the {ntpqman} program. The options are interpreted as
-  follows:
-
-  `time1` _sec_;;
-    Specifies a constant to be added to the time offset produced by the
-    driver, a fixed-point decimal number in seconds. This is used as a
-    calibration constant to adjust the nominal time offset of a
-    particular clock to agree with an external standard, such as a
-    precision PPS signal. It also provides a way to correct a systematic
-    error or bias due to serial port or operating system latencies,
-    different cable lengths or receiver internal delay. The specified
-    offset is in addition to the propagation delay provided by other
-    means, such as internal DIPswitches. Where a calibration for an
-    individual system and driver is available, an approximate correction
-    is noted in the driver documentation pages. Note: in order to
-    facilitate calibration when more than one radio clock or PPS signal
-    is supported, a special calibration feature is available. It takes
-    the form of an argument to the `enable` command described in
-    "Miscellaneous Options" page and operates as described in the
-    "Reference Clock Drivers" page (available as part of the HTML
-    documentation provided in `/usr/share/doc/{ntp}`).
-  `time2` _secs_;;
-    Specifies a fixed-point decimal number in seconds, which is
-    interpreted in a driver-dependent way. See the descriptions of
-    specific drivers in the "Reference Clock Drivers" page (available as
-    part of the HTML documentation provided in `/usr/share/doc/{ntp}`).
-  `stratum` _int_;;
-    Specifies the stratum number assigned to the driver, an integer
-    between 0 and 15. This number overrides the default stratum number
-    ordinarily assigned by the driver itself, usually zero.
-  `refid` _string_;;
-    Specifies an ASCII string of from one to four characters which
-    defines the reference identifier used by the driver. This string
-    overrides the default identifier ordinarily assigned by the driver
-    itself.
-  `mode` _int_;;
-    Specifies a mode number which is interpreted in a device-specific
-    fashion. For instance, it selects a dialing protocol in the ACTS
-    driver and a device subtype in the parse drivers.
-  `flag1` `0` | `1`; `flag2` `0` | `1`; `flag3` `0` | `1`; `flag4` `0` | `1`;;
-    These four flags are used for customizing the clock driver. The
-    interpretation of these values, and whether they are used at all, is
-    a function of the particular clock driver. However, by convention
-    `flag4` is used to enable recording monitoring data to the
-    _clockstats_ file configured with the _filegen_ command. Further
-    information on the _filegen_ command can be found in "Monitoring
-    Options".
+include::../docs/includes/clock-options.txt[]
 
 == Miscellaneous Options ==
 



More information about the vc mailing list