From: Harlan Stenn Date: Wed, 11 May 2011 07:21:39 +0000 (-0400) Subject: Convert snmp docs to mdoc format, which requires autogen 5.11.9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0d003fcd29e4c1cffb6eae63052d604474692f02;p=thirdparty%2Fntp.git Convert snmp docs to mdoc format, which requires autogen 5.11.9 bk: 4dca3903Fi6L3E0V7v-m8XRNZcFAtQ --- diff --git a/ChangeLog b/ChangeLog index 8dbebf6bd1..cc472567bc 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* Convert snmp docs to mdoc format, which requires autogen 5.11.9. (4.2.7p164) 2011/05/11 Released by Harlan Stenn * [Bug 988] Local clock eats up -g option, so ntpd stops with large initial time offset. diff --git a/sntp/Makefile.am b/sntp/Makefile.am index d7d6463431..0157c21d87 100644 --- a/sntp/Makefile.am +++ b/sntp/Makefile.am @@ -217,8 +217,10 @@ $(srcdir)/sntp-opts.h: $(srcdir)/sntp-opts.c $(srcdir)/sntp-opts.c: $(srcdir)/sntp-opts.def $(srcdir)/include/version.def $(srcdir)/include/copyright.def $(run_ag) sntp-opts.def +# For man pages, use agman-cmd.tpl +# For mdoc pages, use agmdoc-cmd.tpl $(srcdir)/sntp.1: $(srcdir)/sntp-opts.def $(srcdir)/include/version.def $(srcdir)/include/copyright.def - $(run_ag) -DMAN_SECTION=1 -Tagman-cmd.tpl -bsntp sntp-opts.def + $(run_ag) -DMAN_SECTION=1 -Tagmdoc-cmd.tpl sntp-opts.def $(srcdir)/sntp-opts.menu: $(srcdir)/sntp-opts.texi @: do-nothing action to avoid default SCCS get, .menu built with .texi diff --git a/sntp/include/autogen-version.def b/sntp/include/autogen-version.def index 89439830eb..d69457ccf1 100644 --- a/sntp/include/autogen-version.def +++ b/sntp/include/autogen-version.def @@ -1,2 +1,2 @@ -#assert (version-compare >= autogen-version "5.9.1") +#assert (version-compare >= autogen-version "5.11.9") guard-option-names; diff --git a/sntp/sntp-opts.def b/sntp/sntp-opts.def index 309f9be207..0d896b4540 100644 --- a/sntp/sntp-opts.def +++ b/sntp/sntp-opts.def @@ -4,7 +4,6 @@ autogen definitions options; #include autogen-version.def #include copyright.def -#include debug-opt.def prog-name = "sntp"; prog-title = "standard Simple Network Time Protocol program"; @@ -28,62 +27,63 @@ environrc; test-main; flag = { - name = ipv4; - value = 4; - flags-cant = ipv6; - descrip = "Force IPv4 DNS name resolution"; - doc = <<- _EndOfDoc_ + name = ipv4; + value = 4; + flags-cant = ipv6; + descrip = "Force IPv4 DNS name resolution"; + doc = <<- _EndOfDoc_ Force DNS resolution of following host names on the command line to the IPv4 namespace. _EndOfDoc_; }; flag = { - name = ipv6; - value = 6; - flags-cant = ipv4; - descrip = "Force IPv6 DNS name resolution"; - doc = <<- _EndOfDoc_ + name = ipv6; + value = 6; + flags-cant = ipv4; + descrip = "Force IPv6 DNS name resolution"; + doc = <<- _EndOfDoc_ Force DNS resolution of following host names on the command line to the IPv6 namespace. _EndOfDoc_; }; flag = { - name = authentication; - value = a; - descrip = "Enable authentication with the key auth-keynumber"; - arg-type = number; - arg-name = "auth-keynumber"; - doc = <<- _EndOfDoc_ - This option enables authentication using the key specified in this option's argument. - The argument of this option is the keyid, a number specified in the keyfile as this - key's identifier. See the keyfile option (-k) for more details. + name = authentication; + value = a; + descrip = "Enable authentication with the key auth-keynumber"; + arg-type = number; + arg-name = "auth-keynumber"; + doc = <<- _EndOfDoc_ + This option enables authentication using the key specified in this + option's argument. The argument of this option is the keyid, a + number specified in the keyfile as this key's identifier. See the + keyfile option (-k) for more details. _EndOfDoc_; }; flag = { - name = bctimeout; - value = B; - descrip = "The number of seconds to wait for broadcasts"; - arg-type = number; - arg-name = "seconds"; - arg-default = 68; - doc = <<- _EndOfDoc_ + name = bctimeout; + value = B; + descrip = "The number of seconds to wait for broadcasts"; + arg-type = number; + arg-name = "seconds"; + arg-default = 68; + doc = <<- _EndOfDoc_ When waiting for a broadcast packet SNTP will wait the number of seconds specified before giving up. Default 68 seconds. _EndOfDoc_; }; flag = { - name = broadcast; - value = b; - descrip = "Listen to the address specified for broadcast time sync"; - arg-type = string; - arg-name = "broadcast-address"; - max = NOLIMIT; - stack-arg; - doc = <<- _EndOfDoc_ + name = broadcast; + value = b; + descrip = "Listen to the address specified for broadcast time sync"; + arg-type = string; + arg-name = "broadcast-address"; + max = NOLIMIT; + stack-arg; + doc = <<- _EndOfDoc_ If specified SNTP will listen to the specified address for NTP broadcasts. The default maximum wait time, 68 seconds, can be modified with -B. @@ -91,34 +91,36 @@ flag = { }; flag = { - name = concurrent; - value = c; - descrip = "Concurrent query all IPs returned for host-name"; - arg-type = string; - arg-name = "host-name"; - max = NOLIMIT; - stack-arg; - doc = <<- _EndOfDoc_ + name = concurrent; + value = c; + descrip = "Concurrent query all IPs returned for host-name"; + arg-type = string; + arg-name = "host-name"; + max = NOLIMIT; + stack-arg; + doc = <<- _EndOfDoc_ Requests from an NTP "client" to a "server" should never be sent more rapidly than one every 2 seconds. By default, any IPs returned as part of a DNS lookup are assumed to be for a single instance of - ntpd, and therefore sntp will send queries to these IPs one after + ntpd, and therefore sntp will send queries to these IPs one after another, with a 2-second gap in between each query. - The -c or --concurrent flag says that any IPs returned for the - DNS lookup of the supplied host-name are on different machines, - so we can send concurrent queries. + The -c or --concurrent flag says that any IPs returned for the DNS + lookup of the supplied host-name are on different machines, so we + can send concurrent queries. _EndOfDoc_; }; +#include debug-opt.def + flag = { - name = headspace; - value = h; - descrip = "The gap (in milliseconds) between time requests"; - arg-type = number; - arg-name = "milliseconds"; - arg-default = 10; - doc = <<- _EndOfDoc_ + name = headspace; + value = h; + descrip = "The gap (in milliseconds) between time requests"; + arg-type = number; + arg-name = "milliseconds"; + arg-default = 10; + doc = <<- _EndOfDoc_ Since we're only going to use the first valid response we get and there is benefit to specifying a good number of servers to query, separate the queries we send out by the specified number of @@ -128,27 +130,28 @@ flag = { }; flag = { - name = kod; - value = K; - arg-type = file; - arg-name = "file-name"; - arg-default = "/var/db/ntp-kod"; - descrip = "KoD history filename"; - doc = <<- _EndOfDoc_ - Specifies the filename to be used for the persistent history of KoD + name = kod; + value = K; + arg-type = file; + arg-name = "file-name"; + arg-default = "/var/db/ntp-kod"; + descrip = "KoD history filename"; + doc = <<- _EndOfDoc_ + Specifies the filename to be used for the persistent history of KoD responses received from servers. The default is - /var/db/ntp-kod. + /var/db/ntp-kod . _EndOfDoc_; }; flag = { - name = keyfile; - value = k; - descrip = "Look in this file for the key specified with -a"; - arg-type = file; - arg-name = "file-name"; - doc = <<- _EndOfDoc_ - This option specifies the keyfile. SNTP will search for the key specified with -a keyno in this + name = keyfile; + value = k; + descrip = "Look in this file for the key specified with -a"; + arg-type = file; + arg-name = "file-name"; + doc = <<- _EndOfDoc_ + This option specifies the keyfile. + SNTP will search for the key specified with -a keyno in this file. Key files follow the following format: keyid keytype key @@ -165,87 +168,90 @@ flag = { }; flag = { - name = filelog; - value = l; - arg-type = file; - arg-name = "file-name"; - descrip = "Log to specified logfile"; - doc = <<- _EndOfDoc_ + name = filelog; + value = l; + arg-type = file; + arg-name = "file-name"; + descrip = "Log to specified logfile"; + doc = <<- _EndOfDoc_ This option causes the client to write log messages to the specified logfile. _EndOfDoc_; }; flag = { - name = steplimit; - value = M; - arg-type = number; - arg-range = "0->"; - descrip = "Adjustments less than steplimit msec will be slewed."; - doc = <<- _EndOfDoc_ - If the time adjustment is less than steplimit milliseconds, slew the amount using adjtime(). Otherwise, step the correction using settimeofday(). + name = steplimit; + value = M; + arg-type = number; + arg-range = "0->"; + descrip = "Adjustments less than steplimit msec will be slewed."; + doc = <<- _EndOfDoc_ + If the time adjustment is less than steplimit milliseconds, slew the + amount using adjtime(). Otherwise, step the correction using + settimeofday(). _EndOfDoc_; - }; +}; flag = { - name = ntpversion; - value = o; - descrip = "Send as our NTP version"; - arg-type = number; - arg-default = 4; - arg-range = "0->7"; - doc = <<- _EndOfDoc_ + name = ntpversion; + value = o; + descrip = "Send as our NTP version"; + arg-type = number; + arg-default = 4; + arg-range = "0->7"; + doc = <<- _EndOfDoc_ When sending requests to a remote server, tell them we are running NTP protocol version . _EndOfDoc_; }; flag = { - name = usereservedport; - value = r; - descrip = "Use the NTP Reserved Port (port 123)"; - doc = <<- _EndOfDoc_ - Use port 123, which is reserved for NTP, for our network communications. + name = usereservedport; + value = r; + descrip = "Use the NTP Reserved Port (port 123)"; + doc = <<- _EndOfDoc_ + Use port 123, which is reserved for NTP, for our network + communications. _EndOfDoc_; }; flag = { - name = step; - value = S; - descrip = "OK to 'step' the time with settimeofday()"; - doc = <<- _EndOfDoc_ + name = step; + value = S; + descrip = "OK to 'step' the time with settimeofday()"; + doc = <<- _EndOfDoc_ _EndOfDoc_; }; flag = { - name = slew; - value = s; - descrip = "OK to 'slew' the time with adjtime()"; - doc = <<- _EndOfDoc_ + name = slew; + value = s; + descrip = "OK to 'slew' the time with adjtime()"; + doc = <<- _EndOfDoc_ _EndOfDoc_; }; flag = { - name = uctimeout; - value = u; - descrip = "The number of seconds to wait for unicast responses"; - arg-type = number; - arg-name = "seconds"; - arg-default = 5; - doc = <<- _EndOfDoc_ + name = uctimeout; + value = u; + descrip = "The number of seconds to wait for unicast responses"; + arg-type = number; + arg-name = "seconds"; + arg-default = 5; + doc = <<- _EndOfDoc_ When waiting for a unicast reply, SNTP will wait the number of seconds specified before giving up. Default 5 seconds. _EndOfDoc_; }; flag = { - name = "wait"; - descrip = "Wait for pending replies (if not setting the time)"; - disable = no; - enabled; - settable; - doc = <<- _EndOfDoc_ + name = "wait"; + descrip = "Wait for pending replies (if not setting the time)"; + disable = no; + enabled; + settable; + doc = <<- _EndOfDoc_ If we are not setting the time, wait for all pending responses. _EndOfDoc_; }; @@ -265,12 +271,15 @@ NTP and SNTP are defined by RFC 5905, which obsoletes RFC 4330 and RFC 1305. _END_DETAIL; -prog-man-descrip = <<- _END_PROG_MAN_DESCRIP -.I sntp +doc-section = { + ds-type = 'DESCRIPTION'; + ds-format = 'mdoc'; + ds-text = <<- _END_PROG_MDOC_DESCRIP +.Nm can be used as a SNTP client to query a NTP or SNTP server and either display the time or set the local system's time (given suitable privilege). It can be run as an interactive command or in a -.I cron +.Ic cron job. NTP (the Network Time Protocol) and SNTP (the Simple Network Time Protocol) @@ -278,22 +287,25 @@ are defined and described by RFC 5905. .PP The default is to write the estimated correct local date and time (i.e. not -UTC) to the standard output in a format like -.BR "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" , +UTC) to the standard output in a format like: + +.Ic "'1996-10-15 20:17:25.123 (+0800) +4.567 +/- 0.089 secs'" + where the -.B "'(+0800)'" +.Ic "'(+0800)'" means that to get to UTC from the reported local time one must add 8 hours and 0 minutes, and the -.B "'+4.567 +/- 0.089 secs'" +.Ic "'+4.567 +/- 0.089 secs'" indicates the local clock is 4.567 seconds behind the correct time (so 4.567 seconds must be added to the local clock to get it to be correct), -and the time of +and the date/time of '1996-10-15 20:17:25.123' is believed to be correct to within +/- 0.089 seconds. - _END_PROG_MAN_DESCRIP; + _END_PROG_MDOC_DESCRIP; +}; prog-info-descrip = <<- _END_PROG_INFO_DESCRIP @code{sntp} @@ -326,7 +338,10 @@ is believed to be correct to within seconds. _END_PROG_INFO_DESCRIP; -man-doc = <<- _END_MAN_DOC +doc-section = { + ds-type = 'USAGE'; + ds-format = 'man'; + ds-text = <<- _END_MAN_DOC .SH USAGE The simplest use of this program is as an unprivileged command to check the current time and error in the local clock. For example: @@ -348,3 +363,4 @@ status for success, and a non-zero one otherwise. .SH BUGS Please report bugs to http://bugs.ntp.org . _END_MAN_DOC; +}; diff --git a/sntp/sntp.texi b/sntp/sntp.texi index 2c8de936c8..1f8935dec8 100644 --- a/sntp/sntp.texi +++ b/sntp/sntp.texi @@ -2,7 +2,7 @@ @c %**start of header @setfilename sntp.info @settitle Sntp User's Manual -@include version.texi +@include include/version.texi @paragraphindent 2 @c %**end of header