From d0a26b2cf39b10d034bc20db81eadcdff79352d2 Mon Sep 17 00:00:00 2001 From: Harlan Stenn Date: Sun, 13 Jan 2013 09:53:41 +0000 Subject: [PATCH] Documentation cleanup to various .def files bk: 50f28425ZM6s37kOWmCJcxAUTzCqHA --- ntpd/ntpd-opts.def | 30 +++++++++++++++--------------- ntpdc/ntpdc-opts.def | 24 ++++++++++++------------ ntpq/ntpq-opts.def | 19 +++++++++++-------- scripts/ntp-wait-opts.def | 12 ++++++------ 4 files changed, 44 insertions(+), 41 deletions(-) diff --git a/ntpd/ntpd-opts.def b/ntpd/ntpd-opts.def index 94157fdcf..12fcda676 100644 --- a/ntpd/ntpd-opts.def +++ b/ntpd/ntpd-opts.def @@ -72,9 +72,9 @@ configuration options altered while the .Nm is running using the -.Xr ntpq 8 +.Xr ntpq 1ntpqmdoc and -.Xr ntpdc 8 +.Xr ntpdc 1ntpdcmdoc utility programs. .Pp When @@ -235,13 +235,13 @@ when you have permission to do so from the owner of the target host. .Pp Finally, in the past many startup scripts would run -.Xr ntpdate 8 +.Xr ntpdate 1ntpdatemdoc to get the system clock close to correct before starting -.Xr ntpd 8 , +.Xr ntpd 1ntpdmdoc , but this was never more than a mediocre hack and is no longer needed. .Pp There is a way to start -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc that often addresses all of the problems mentioned above. .Ss "Starting NTP (Best Current Practice)" First, use the @@ -253,12 +253,12 @@ entries. If you can also keep a good .Pa ntp.drift file then -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc will effectively "warm-start" and your system's clock will be stable in under 11 seconds' time. .Pp As soon as possible in the startup sequence, start -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc with at least the .Fl g and perhaps the @@ -267,7 +267,7 @@ options. Then, start the rest of your "normal" processes. This will give -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc as much time as possible to get the system's clock synchronized and stable. .Pp Finally, @@ -277,13 +277,13 @@ or database servers that require monotonically-increasing time, run -.Xr ntp-wait 8 +.Xr ntp-wait 1ntp-waitmdoc as late as possible in the boot sequence (perhaps with the .Fl v flag) and after -.Xr ntp-wait 8 +.Xr ntp-wait 1ntp-waitmdoc exits successfully it is as safe as it will ever be to start any process that require stable time. @@ -365,7 +365,7 @@ In some cases it may not be practical for to run continuously. A common workaround has been to run the -.Xr ntpdate 8 +.Xr ntpdate 1ntpdatemdoc program from a .Xr cron 8 job at designated @@ -394,7 +394,7 @@ If nothing is heard after a couple of minutes, the daemon times out and exits. After a suitable period of mourning, the -.Xr ntpdate 8 +.Xr ntpdate 1ntpdatemdoc program may be retired. .Pp @@ -521,9 +521,9 @@ doc-section = { ds-format = 'mdoc'; ds-text = <<- _END_MDOC_SEE_ALSO .Xr ntp.conf 5 , -.Xr ntpdate 8 , -.Xr ntpdc 8 , -.Xr ntpq 8 +.Xr ntpdate 1ntpdatemdoc , +.Xr ntpdc 1ntpdcmdoc , +.Xr ntpq 1ntpqmdoc .Pp In addition to the manual pages provided, comprehensive documentation is available on the world wide web diff --git a/ntpdc/ntpdc-opts.def b/ntpdc/ntpdc-opts.def index e158ac852..13466df46 100644 --- a/ntpdc/ntpdc-opts.def +++ b/ntpdc/ntpdc-opts.def @@ -116,7 +116,7 @@ doc-section = { ds-text = <<- _END_PROG_MDOC_DESCRIP .Nm is a utility program used to query -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc about its current state and to request changes in that state. It uses NTP mode 7 control message formats described in the source code. @@ -176,7 +176,7 @@ The operation of .Nm are specific to the particular implementation of the -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc daemon and can be expected to work only with this and maybe some previous versions of the daemon. Requests from a remote @@ -235,7 +235,7 @@ followed by a command keyword will print function and usage information about the command. This command is probably a better source of information about -.Xr ntpq 8 +.Xr ntpq 1ntpqmdoc than this manual page. .It Ic delay Ar milliseconds @@ -440,7 +440,7 @@ and .Cm stats flags. See the -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc documentation for the meaning of these flags. There are two additional flags which are read only, the @@ -652,7 +652,7 @@ These commands operate in the same way as the and .Ic disable configuration file commands of -.Xr ntpd 8 . +.Xr ntpd 1ntpdmdoc . .Bl -tag -width indent .It Cm auth Enables the server to synchronize with unconfigured peers only @@ -672,9 +672,9 @@ Enables the kernel time discipline, if available. The default for this flag is enable if support is available, otherwise disable. .It Cm monitor Enables the monitoring facility. -See the -.Xr ntpdc 8 . -program and the monlist command or further information. +See the documentation here about the +.Cm monlist +command or further information. The default for this flag is enable. .It Cm ntp Enables time and frequency discipline. @@ -706,7 +706,7 @@ The default for this flag is disable. This command operates in the same way as the .Ic restrict configuration file commands of -.Xr ntpd 8 . +.Xr ntpd 1ntpdmdoc . .It Xo Ic unrestrict Ar address Ar mask .Ar flag Oo Ar ... Oc .Xc @@ -719,7 +719,7 @@ Delete the matching entry from the restrict list. Causes the current set of authentication keys to be purged and a new set to be obtained by rereading the keys file (which must have been specified in the -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc configuration file). This allows encryption keys to be changed without restarting the @@ -732,7 +732,7 @@ and .Ic untrustedkey configuration file commands of -.Xr ntpd 8 . +.Xr ntpd 1ntpdmdoc . .It Ic authinfo Returns information concerning the authentication module, including known keys and counts of encryptions and decryptions @@ -768,7 +768,7 @@ doc-section = { ds-format = 'mdoc'; ds-text = <<- _END_MDOC_SEEALSO .Xr ntp.conf 5 , -.Xr ntpd 8 +.Xr ntpd 1ntpdmdoc .Rs .%A David L. Mills .%T Network Time Protocol (Version 3) diff --git a/ntpq/ntpq-opts.def b/ntpq/ntpq-opts.def index a85f2b238..68b6ef53c 100644 --- a/ntpq/ntpq-opts.def +++ b/ntpq/ntpq-opts.def @@ -69,8 +69,9 @@ flag = { flags-cant = command, peers; descrip = "Force ntpq to operate in interactive mode"; doc = <<- _EndOfDoc_ - Force ntpq to operate in interactive mode. Prompts will be written - to the standard output and commands read from the standard input. + Force @code{ntpq} to operate in interactive mode. + Prompts will be written to the standard output and + commands read from the standard input. _EndOfDoc_; }; @@ -88,13 +89,15 @@ flag = { name = old-rv; descrip = "Always output status line with readvar"; doc = <<- _EndOfDoc_ - By default, ntpq now suppresses the associd=... line that - precedes the output of "readvar" (alias "rv") when a single - variable is requested, such as ntpq -c "rv 0 offset". This - option causes ntpq to include both lines of output for a - single-variable readvar. Using an environment variable to + By default, @code{ntpq} now suppresses the @code{associd=...} + line that precedes the output of @code{readvar} + (alias @code{rv}) when a single variable is requested, such as + @code{ntpq -c "rv 0 offset"}. + This option causes @code{ntpq} to include both lines of output + for a single-variable @code{readvar}. + Using an environment variable to preset this option in a script will enable both older and - newer ntpq to behave identically in this regard. + newer @code{ntpq} to behave identically in this regard. _EndOfDoc_; }; diff --git a/scripts/ntp-wait-opts.def b/scripts/ntp-wait-opts.def index 0daa6c67e..72aaaa698 100644 --- a/scripts/ntp-wait-opts.def +++ b/scripts/ntp-wait-opts.def @@ -21,8 +21,8 @@ flag = { arg-default = 100; descrip = "Number of times to check ntpd"; doc = <<- _EndOfDoc_ - The maximum number of times we will check ntpd to see if it - has been able to synchronize and stabilize the system clock. + The maximum number of times we will check @code{ntpd} to see if + it has been able to synchronize and stabilize the system clock. _EndOfDoc_; }; @@ -33,8 +33,8 @@ flag = { arg-default = 6; descrip = "How long to sleep between tries"; doc = <<- _EndOfDoc_ - We will sleep for @file{secs-between-tries} after each query of ntpd - that returns "the time is not yet stable". + We will sleep for @file{secs-between-tries} after each query + of @code{ntpd} that returns "the time is not yet stable". _EndOfDoc_; }; @@ -42,8 +42,8 @@ flag = { value = v; descrip = "Be verbose"; doc = <<- _EndOfDoc_ - By default, ntp-wait is silent. With this option, ntp-wait - will provide status information. + By default, @code{ntp-wait} is silent. + With this option, @code{ntp-wait} will provide status information. _EndOfDoc_; }; -- 2.47.3