From: Harlan Stenn Date: Sat, 4 Jun 2011 08:22:32 +0000 (-0400) Subject: Produce ntpq.1 with the new autogen macros X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c2bc0d84f907f558ca56a52474b973be043a233b;p=thirdparty%2Fntp.git Produce ntpq.1 with the new autogen macros bk: 4de9eb4895PxPqUrdIaYVVkjFL9XYQ --- diff --git a/ChangeLog b/ChangeLog index ce5a3112d8..9db2efb2ca 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,4 @@ +* Produce ntpq.1 with the new autogen macros. * Remove the deprecated "detail" stanza from ntpdc-opts.def. (4.2.7p179) 2011/06/03 Released by Harlan Stenn * Update cmd-doc.tlib to autogen-5.11.10pre5. diff --git a/ntpq/Makefile.am b/ntpq/Makefile.am index c365ca0cf6..54615880e9 100644 --- a/ntpq/Makefile.am +++ b/ntpq/Makefile.am @@ -46,8 +46,13 @@ $(srcdir)/ntpq-opts.h: $(srcdir)/ntpq-opts.c $(srcdir)/ntpq-opts.c: $(srcdir)/ntpq-opts.def $(std_def_list) $(run_ag) ntpq-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 -Tagmdoc-cmd.tpl sntp-opts.def +### $(srcdir)/ntpq.1: $(srcdir)/ntpq-opts.def $(std_def_list) - $(run_ag) -Tagman1.tpl -bntpq ntpq-opts.def + $(run_ag) -DMAN_SECTION=1 -Tagmdoc-cmd.tpl ntpq-opts.def $(srcdir)/ntpq-opts.menu: $(srcdir)/ntpq-opts.texi @: do-nothing action to avoid default SCCS get, .menu built with .texi diff --git a/ntpq/ntpq-opts.def b/ntpq/ntpq-opts.def index 8845aa3204..a85f2b2381 100644 --- a/ntpq/ntpq-opts.def +++ b/ntpq/ntpq-opts.def @@ -98,263 +98,258 @@ flag = { _EndOfDoc_; }; -detail = <<- _END_DETAIL - The - [= prog-name =] - utility program is used to query NTP servers which - implement the standard NTP mode 6 control message formats defined - in Appendix B of the NTPv3 specification RFC1305, requesting - information about current state and/or changes in that state. - The same formats are used in NTPv4, although some of the - variables have changed and new ones added. - _END_DETAIL; +doc-section = { + ds-type = 'DESCRIPTION'; + ds-format = 'mdoc'; + ds-text = <<- _END_PROG_MDOC_DESCRIP -prog-man-descrip = <<- _END_PROG_MAN_DESCRIP - The - [= prog-name =] - utility program is used to query NTP servers which - implement the standard NTP mode 6 control message formats defined - in Appendix B of the NTPv3 specification RFC1305, requesting - information about current state and/or changes in that state. - The same formats are used in NTPv4, although some of the - variables have changed and new ones added. The description on this - page is for the NTPv4 variables. - The program may be run either in interactive mode or controlled using - command line arguments. - Requests to read and write arbitrary - variables can be assembled, with raw and pretty-printed output - options being available. - The - [= prog-name =] - utility can also obtain and print a - list of peers in a common format by sending multiple queries to the - server. +The +.Nm +utility program is used to query NTP servers which +implement the standard NTP mode 6 control message formats defined +in Appendix B of the NTPv3 specification RFC1305, requesting +information about current state and/or changes in that state. +The same formats are used in NTPv4, although some of the +variables have changed and new ones added. The description on this +page is for the NTPv4 variables. +The program may be run either in interactive mode or controlled using +command line arguments. +Requests to read and write arbitrary +variables can be assembled, with raw and pretty-printed output +options being available. +The +.Nm +utility can also obtain and print a +list of peers in a common format by sending multiple queries to the +server. - If one or more request options is included on the command line - when - [= prog-name =] - is executed, each of the requests will be sent - to the NTP servers running on each of the hosts given as command - line arguments, or on localhost by default. - If no request options - are given, - [= prog-name =] - will attempt to read commands from the - standard input and execute these on the NTP server running on the - first host given on the command line, again defaulting to localhost - when no other host is specified. - The - [= prog-name =] - utility will prompt for - commands if the standard input is a terminal device. +If one or more request options is included on the command line +when +.Nm +is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. +If no request options +are given, +.Nm +will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. +The +.Nm +utility will prompt for +commands if the standard input is a terminal device. - The - [= prog-name =] - utility uses NTP mode 6 packets to communicate with the - NTP server, and hence can be used to query any compatible server on - the network which permits it. - Note that since NTP is a UDP protocol - this communication will be somewhat unreliable, especially over - large distances in terms of network topology. - The - [= prog-name =] - utility makes - one attempt to retransmit requests, and will time requests out if - the remote host is not heard from within a suitable timeout - time. +.Nm +uses NTP mode 6 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. +Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. +The +.Nm +utility makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time. - Specifying a - command line option other than - .Fl i - or - .Fl n - will - cause the specified query (queries) to be sent to the indicated - host(s) immediately. - Otherwise, - [= prog-name =] - will attempt to read - interactive format commands from the standard input. - .Ss "Internal Commands" - Interactive format commands consist of a keyword followed by zero - to four arguments. - Only enough characters of the full keyword to - uniquely identify the command need be typed. +Specifying a +command line option other than +.Fl i +or +.Fl n +will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. +Otherwise, +.Nm +will attempt to read +interactive format commands from the standard input. +.Ss "Internal Commands" +Interactive format commands consist of a keyword followed by zero +to four arguments. +Only enough characters of the full keyword to +uniquely identify the command need be typed. - A - number of interactive format commands are executed entirely within - the - [= prog-name =] - utility itself and do not result in NTP mode 6 - requests being sent to a server. - These are described following. - @table @code - @item ? [command_keyword] - @itemx help [command_keyword] - A - .Ql \&? - by itself will print a list of all the command - keywords known to this incarnation of - [= prog-name =] . - A - .Ql \&? - followed by a command keyword will print function and usage - information about the command. - This command is probably a better - source of information about - [= prog-name =] - than this manual - page. - @item addvars - .Ar variable_name [=value] ... - .Xc - @item rmvars variable_name ... - @item clearvars - The data carried by NTP mode 6 messages consists of a list of - items of the form - .Ql variable_name=value , - where the - .Ql =value - is ignored, and can be omitted, - in requests to the server to read variables. - The - [= prog-name =] - utility maintains an internal list in which data to be included in control - messages can be assembled, and sent using the - .Ic readlist - and - .Ic writelist - commands described below. - The - .Ic addvars - command allows variables and their optional values to be added to - the list. - If more than one variable is to be added, the list should - be comma-separated and not contain white space. - The - .Ic rmvars - command can be used to remove individual variables from the list, - while the - .Ic clearlist - command removes all variables from the - list. - @item authenticate [ yes | no ] - Normally - [= prog-name =] - does not authenticate requests unless - they are write requests. - The command - .Ql authenticate yes - causes - [= prog-name =] - to send authentication with all requests it - makes. - Authenticated requests causes some servers to handle - requests slightly differently, and can occasionally melt the CPU in - fuzzballs if you turn authentication on before doing a - .Ic peer - display. - The command - .Ql authenticate - causes - [= prog-name =] - to display whether or not - [= prog-name =] - is currently autheinticating requests. - @item cooked - Causes output from query commands to be "cooked", so that - variables which are recognized by - [= prog-name =] - will have their - values reformatted for human consumption. - Variables which - [= prog-name =] - thinks should have a decodable value but didn't are - marked with a trailing - .Ql \&? . - .@item debug [ - .Cm more | - .Cm less | - .Cm off - ] - .Xc - With no argument, displays the current debug level. - Otherwise, the debug level is changed to the indicated level. - @item delay milliseconds - Specify a time interval to be added to timestamps included in - requests which require authentication. - This is used to enable - (unreliable) server reconfiguration over long delay network paths - or between machines whose clocks are unsynchronized. - Actually the - server does not now require timestamps in authenticated requests, - so this command may be obsolete. - @item host hostname - Set the host to which future queries will be sent. - Hostname may - be either a host name or a numeric address. - @item hostnames Cm yes | Cm no - If - .Cm yes - is specified, host names are printed in - information displays. - If - .Cm no - is specified, numeric - addresses are printed instead. - The default is - .Cm yes , - unless - modified using the command line - .Fl n - switch. - @item keyid keyid - This command allows the specification of a key number to be - used to authenticate configuration requests. - This must correspond - to a key number the server has been configured to use for this - purpose. - @item ntpversion [ - .Cm 1 | - .Cm 2 | - .Cm 3 | - .Cm 4 - ] - .Xc - Sets the NTP version number which - [= prog-name =] - claims in - packets. - Defaults to 3, Note that mode 6 control messages (and - modes, for that matter) didn't exist in NTP version 1. - There appear - to be no servers left which demand version 1. - With no argument, displays the current NTP version that will be used - when communicating with servers. - @item quit - Exit - [= prog-name =] . - @item passwd - This command prompts you to type in a password (which will not - be echoed) which will be used to authenticate configuration - requests. - The password must correspond to the key configured for - use by the NTP server for this purpose if such requests are to be - successful. - @item raw - Causes all output from query commands is printed as received - from the remote server. - The only formating/interpretation done on - the data is to transform nonascii data into a printable (but barely - understandable) form. - @item timeout Ar milliseconds - Specify a timeout period for responses to server queries. - The - default is about 5000 milliseconds. - Note that since - [= prog-name =] - retries each query once after a timeout, the total waiting time for - a timeout will be twice the timeout value set. - @end table +A +number of interactive format commands are executed entirely within +the +.Nm +utility itself and do not result in NTP mode 6 +requests being sent to a server. +These are described following. +.Bl -tag -width "? [command_keyword]" -compact -offset indent +.It Ic ? Op Ar command_keyword +.It Ic help Op Ar command_keyword +A +.Ql \&? +by itself will print a list of all the command +keywords known to this incarnation of +.Nm . +A +.Ql \&? +followed by a command keyword will print function and usage +information about the command. +This command is probably a better +source of information about +.Nm +than this manual +page. +.It Ic addvars Ar variable_name Xo Op Ic =value +.Ic ... +.Xc +.It Ic rmvars Ar variable_name Ic ... +.It Ic clearvars +The data carried by NTP mode 6 messages consists of a list of +items of the form +.Ql variable_name=value , +where the +.Ql =value +is ignored, and can be omitted, +in requests to the server to read variables. +The +.Nm +utility maintains an internal list in which data to be included in control +messages can be assembled, and sent using the +.Ic readlist +and +.Ic writelist +commands described below. +The +.Ic addvars +command allows variables and their optional values to be added to +the list. +If more than one variable is to be added, the list should +be comma-separated and not contain white space. +The +.Ic rmvars +command can be used to remove individual variables from the list, +while the +.Ic clearlist +command removes all variables from the +list. +.It Ic authenticate Op yes | no +Normally +.Nm +does not authenticate requests unless +they are write requests. +The command +.Ql authenticate yes +causes +.Nm +to send authentication with all requests it +makes. +Authenticated requests causes some servers to handle +requests slightly differently, and can occasionally melt the CPU in +fuzzballs if you turn authentication on before doing a +.Ic peer +display. +The command +.Ql authenticate +causes +.Nm +to display whether or not +.Nm +is currently autheinticating requests. +.It Ic cooked +Causes output from query commands to be "cooked", so that +variables which are recognized by +.Nm +will have their +values reformatted for human consumption. +Variables which +.Nm +thinks should have a decodable value but didn't are +marked with a trailing +.Ql \&? . +.It Xo +.Ic debug +.Oo +.Cm more | +.Cm less | +.Cm off +.Oc +.Xc +With no argument, displays the current debug level. +Otherwise, the debug level is changed to the indicated level. +.It Ic delay Ar milliseconds +Specify a time interval to be added to timestamps included in +requests which require authentication. +This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. +Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete. +.It Ic host Ar hostname +Set the host to which future queries will be sent. +.Ar hostname +may be either a host name or a numeric address. +.It Ic hostnames Op Cm yes | Cm no +If +.Cm yes +is specified, host names are printed in +information displays. +If +.Cm no +is specified, numeric +addresses are printed instead. +The default is +.Cm yes , +unless +modified using the command line +.Fl n +switch. +.It Ic keyid Ar keyid +This command allows the specification of a key number to be +used to authenticate configuration requests. +This must correspond +to a key number the server has been configured to use for this +purpose. +.It Ic ntpversion Xo Oo +.Cm 1 | +.Cm 2 | +.Cm 3 | +.Cm 4 +.Oc +.Xc +Sets the NTP version number which +.Nm +claims in +packets. +Defaults to 3, and note that mode 6 control messages (and +modes, for that matter) didn't exist in NTP version 1. +There appear +to be no servers left which demand version 1. +With no argument, displays the current NTP version that will be used +when communicating with servers. +.It Ic quit +Exit +.Nm +.It Ic passwd +This command prompts you to type in a password (which will not +be echoed) which will be used to authenticate configuration +requests. +The password must correspond to the key configured for +use by the NTP server for this purpose if such requests are to be +successful. +.It Ic raw +Causes all output from query commands is printed as received +from the remote server. +The only formating/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form. +.It Ic timeout Ar milliseconds +Specify a timeout period for responses to server queries. +The +default is about 5000 milliseconds. +Note that since +.Nm +retries each query once after a timeout, the total waiting time for +a timeout will be twice the timeout value set. +.El - _END_PROG_MAN_DESCRIP; + _END_PROG_MDOC_DESCRIP; +};