[ntpsec commit] Simplify and correct man-page generation.
Eric S. Raymond
esr at ntpsec.org
Mon Oct 19 22:18:31 UTC 2015
Module: ntpsec
Branch: master
Commit: 08c7f90fcb036256ba1ade746de7deeefb66b9e3
Changeset: http://git.ntpsec.org/ntpsec/commit/?id=08c7f90fcb036256ba1ade746de7deeefb66b9e3
Author: Eric S. Raymond <esr at thyrsus.com>
Date: Mon Oct 19 18:17:24 2015 -0400
Simplify and correct man-page generation.
No more preprocessing stage. All pages are now syntactically valid.
---
devel-docs/TODO | 10 ++-----
devel-docs/hacking.txt | 7 -----
docs/includes/ntpdig-body.txt | 4 +--
docs/includes/ntpleapfetch-body.txt | 8 ++----
docs/ntpspeak.txt | 13 +++++++--
ntpd/{complete.conf.in => complete.conf} | 0
ntpd/{ntpd-man.txt.in => ntpd-man.txt} | 4 +--
ntpdig/{ntpdig-man.txt.in => ntpdig-man.txt} | 4 +--
ntpfrob/ntpfrob-man.txt | 19 +++++++++++++
.../{ntpkeygen-man.txt.in => ntpkeygen-man.txt} | 4 +--
.../{ntpleapfetch.txt.in => ntpleapfetch-man.txt} | 6 ++--
ntpq/{ntpq-man.txt.in => ntpq-man.txt} | 6 ++--
.../ntpsweep/{ntpsweep.txt => ntpsweep-man.txt} | 14 ++++-----
.../{ntptrace-man.txt.in => ntptrace-man.txt} | 4 +--
.../ntpwait/ntpwait-man.txt | 8 +++---
scripts/ntpwait/ntpwait-man.txt.in | 19 -------------
util/{ntptime-man.txt.in => ntptime-man.txt} | 6 ++--
wscript | 33 +++++++++++-----------
18 files changed, 82 insertions(+), 87 deletions(-)
diff --git a/devel-docs/TODO b/devel-docs/TODO
index 801ae8c..f9575e4 100644
--- a/devel-docs/TODO
+++ b/devel-docs/TODO
@@ -15,14 +15,8 @@ None right now. (Sep-22 2015)
* Add 'snapshot' feature to dump config status into a JSON file for collecting
build + platform information
-* @ expansion needs to be made to work fully for *.txt.in files. They
- are not yet doing file inclusions properly - for example, in
- ntpdig/ntpdig-man.txt.in the @../docs/includes/ntpdig-body.txt@ is not
- interpreted.
-
-* The doc target should build manual pages. Previous item about @-expansion
- is a prerequisite for this, then the *-man.txt files need to be passed
- through asciidoc to make generated man pages.
+* The doc target should build manual pages. Model command is
+ a2x --format manpage --asciidoc-opts=--conf-file=../docs/asciidoc.conf foo.txt
* An issue with the install productions as presently written is that
they're written to install to ${PREFIX}/bin and {PREFIX}/sbin. This
diff --git a/devel-docs/hacking.txt b/devel-docs/hacking.txt
index 785f2fe..35ace06 100644
--- a/devel-docs/hacking.txt
+++ b/devel-docs/hacking.txt
@@ -177,13 +177,6 @@ a large common include file. These includes live in docs/includes
and are probably what you need to edit if you're updating anything
that appears on a man page.
-Most manual-page masters actually have the extension *.txt.in. The
-.in part is a convention for files that need to be macroexpanded as a
-first stage for processing. The reason for this is that asciidoc
-becomes syntactically confused if inclusion directives collide with
-its parser's idea of where the next section header should be. We use
-the build system to patch around this problem.
-
=== Conventions for #ifdef guard names ===
Parts of this code are a thicket of C preprocessor conditionals.
diff --git a/docs/includes/ntpdig-body.txt b/docs/includes/ntpdig-body.txt
index 92551cb..8c6b10e 100644
--- a/docs/includes/ntpdig-body.txt
+++ b/docs/includes/ntpdig-body.txt
@@ -2,7 +2,7 @@
// It's included in two places: once for the docs/ HTML
// tree, and once to make an individual man page.
-== SYNOPSIS =
+== SYNOPSIS ==
[verse]
{ntpdig}
[--help | -?] [-4 | -6] [-a keynum] [-b bcaddress] [-B bctimeout]
@@ -30,7 +30,7 @@ time one must add 5 hours and 0 minutes, the +-0.000007+ indicates the
local clock is 0.000007 seconds ahead of correct time (so 0.000007 seconds
must be subtracted from the local clock to get it to be correct). Note that
the number of decimals printed for this value will change based on the
-reported precision of the server.++/- 0.084075+ is the reported
+reported precision of the server. `+/- 0.084075` is the reported
_synchronization_ _distance_ (in seconds), which represents the
maximum error due to all causes. If the server does not report valid
data needed to calculate the synchronization distance, this will be
diff --git a/docs/includes/ntpleapfetch-body.txt b/docs/includes/ntpleapfetch-body.txt
index 0f93ee4..089ff9f 100644
--- a/docs/includes/ntpleapfetch-body.txt
+++ b/docs/includes/ntpleapfetch-body.txt
@@ -68,11 +68,9 @@ Specify location of {ntpconf} (used to make sure leapfile directive is
present and to default leapfile) /etc/{ntpconf}
+-F+::
- Force update of the leapfile.
-+
-Force update even if current file is OK and not close to expiring.
+ Force update even if current file is OK and not close to expiring.
-+-i 'interval'+::
++-i+ 'interval::
Number of retries.
+-l+::
@@ -90,7 +88,7 @@ Force update even if current file is OK and not close to expiring.
+-q+::
Only report errors to stdout
-+-r 'retries'+::
++-r+ 'retries'::
Number of retries.
+-s+ string, +--source-url+=_string_::
diff --git a/docs/ntpspeak.txt b/docs/ntpspeak.txt
index 364556c..d4ee8c7 100644
--- a/docs/ntpspeak.txt
+++ b/docs/ntpspeak.txt
@@ -7,7 +7,16 @@
|==============================
[glossary]
-//association::
+[[association]]
+association::
+ An association is the relationship that an NTP client and server have
+ when the server is computing and shipping time updates to the server
+ and the server is expecting them. There are several different kinds
+ of associations including unicast, manycast, and broadcast modes;
+ another variable is whether the association is authenticated or
+ unauthenticated. A significant amount of NTP's complexity is means
+ for discovering association partners, creating and maintaining
+ associations, and preventing attackers from forming associations.
[[drift]]
drift::
@@ -121,7 +130,7 @@ PPS::
[[proventic]]
proventic::
<<Mills-speak>> for "the transitive completion of the
- authentication relstionship", defined in RFC5906. Time is proventic
+ authentication relationship", defined in RFC5906. Time is proventic
if it is provided by a chain of time servers between which packets
are authenticated and the chain reaches back to Stratum 1.
diff --git a/ntpd/complete.conf.in b/ntpd/complete.conf
similarity index 100%
rename from ntpd/complete.conf.in
rename to ntpd/complete.conf
diff --git a/ntpd/ntpd-man.txt.in b/ntpd/ntpd-man.txt
similarity index 75%
rename from ntpd/ntpd-man.txt.in
rename to ntpd/ntpd-man.txt
index 3d73df5..08c90ac 100644
--- a/ntpd/ntpd-man.txt.in
+++ b/ntpd/ntpd-man.txt
@@ -4,7 +4,7 @@
== NAME ==
ntpd - Network Time Protocol service daemon
- at ../docs/includes/ntpd-body.txt@
+include::../docs/includes/ntpd-body.txt[]
== EXIT STATUS ==
@@ -14,7 +14,7 @@ One of the following exit values will be returned:
Successful program execution.
1 (EXIT_FAILURE)::
- The operation failed or the command syntax was not valid.
+ Execution failed - examine system logfiles.
== SEE ALSO ==
diff --git a/ntpdig/ntpdig-man.txt.in b/ntpdig/ntpdig-man.txt
similarity index 70%
rename from ntpdig/ntpdig-man.txt.in
rename to ntpdig/ntpdig-man.txt
index e3f0951..bf46b36 100644
--- a/ntpdig/ntpdig-man.txt.in
+++ b/ntpdig/ntpdig-man.txt
@@ -2,9 +2,9 @@
:doctype: manpage
== NAME ==
-{ntpdig} - standard Simple Network Time Protocol client program
+ntpdig - standard Simple Network Time Protocol client program
- at ../docs/includes/ntpdig-body.txt@
+include::../docs/includes/ntpdig-body.txt[]
== EXIT STATUS ==
diff --git a/ntpfrob/ntpfrob-man.txt b/ntpfrob/ntpfrob-man.txt
new file mode 100644
index 0000000..a91d17d
--- /dev/null
+++ b/ntpfrob/ntpfrob-man.txt
@@ -0,0 +1,19 @@
+= ntprob(8) =
+:doctype: manpage
+
+== NAME ==
+ntpfrob - frob the clock hardware
+
+include::../docs/includes/ntpfrob-body.txt[]
+
+== EXIT STATUS ==
+
+One of the following exit values will be returned:
+
+0 (EXIT_SUCCESS)::
+ Successful program execution.
+1 (EXIT_FAILURE)::
+ The operation failed or the command invocation was not valid.
+
+
+// end
diff --git a/ntpkeygen/ntpkeygen-man.txt.in b/ntpkeygen/ntpkeygen-man.txt
similarity index 74%
rename from ntpkeygen/ntpkeygen-man.txt.in
rename to ntpkeygen/ntpkeygen-man.txt
index 0b00d50..0bd86f9 100644
--- a/ntpkeygen/ntpkeygen-man.txt.in
+++ b/ntpkeygen/ntpkeygen-man.txt
@@ -2,9 +2,9 @@
:doctype: manpage
== NAME ==
-{ntpkeygen} - create and manage NTP host keys
+ntpkeygen - create and manage NTP host keys
- at ../docs/includes/ntpkeygen-body.txt@
+include::../docs/includes/ntpkeygen-body.txt[]
== EXIT STATUS ==
diff --git a/ntpleapfetch/ntpleapfetch.txt.in b/ntpleapfetch/ntpleapfetch-man.txt
similarity index 69%
rename from ntpleapfetch/ntpleapfetch.txt.in
rename to ntpleapfetch/ntpleapfetch-man.txt
index 627b79a..cb9035c 100644
--- a/ntpleapfetch/ntpleapfetch.txt.in
+++ b/ntpleapfetch/ntpleapfetch-man.txt
@@ -1,10 +1,10 @@
-== ntpleapfetch(8) ==
+= ntpleapfetch(8) =
:doctype: manpage
== NAME ==
-{ntpleapfetch} - leap-seconds file manager/updater
+ntpleapfetch - leap-seconds file manager/updater
- at ..docs/includes/ntpleapfetch-body.txt@
+include::../docs/includes/ntpleapfetch-body.txt[]
== EXIT STATUS ==
diff --git a/ntpq/ntpq-man.txt.in b/ntpq/ntpq-man.txt
similarity index 78%
rename from ntpq/ntpq-man.txt.in
rename to ntpq/ntpq-man.txt
index e5f5c59..77e1a07 100644
--- a/ntpq/ntpq-man.txt.in
+++ b/ntpq/ntpq-man.txt
@@ -1,10 +1,10 @@
-= ntoq(1) =
+= ntpq(1) =
:doctype: manpage
== NAME ==
-{ntpq} - standard NTP query program
+ntpq - standard NTP query program
- at ../docs/includes/ntpq-body.txt@
+include::../docs/includes/ntpq-body.txt[]
== EXIT STATUS ==
diff --git a/scripts/ntpsweep/ntpsweep.txt b/scripts/ntpsweep/ntpsweep-man.txt
similarity index 79%
rename from scripts/ntpsweep/ntpsweep.txt
rename to scripts/ntpsweep/ntpsweep-man.txt
index 5c9f0d8..2a5216b 100644
--- a/scripts/ntpsweep/ntpsweep.txt
+++ b/scripts/ntpsweep/ntpsweep-man.txt
@@ -1,11 +1,11 @@
-== ntpsweep(1) ==
+= ntpsweep(1) =
:doctype: manpage
== NAME ==
ntpsweep - print various informations about given NTP servers
== SYNOPSIS ==
-ntpsweep [-l 'host']... [-p] [-m 'number'] [-s 'prefix'] [-h 'string']
++ntpsweep+ [+-l+ 'host']... [-p] [+-m+ 'number'] [+-s+ 'prefix'] [+-h+ 'string']
== DESCRIPTION ==
@@ -15,24 +15,24 @@ Optionally recursing through all peers.
== OPTIONS ==
-`-l` string, `--host-list`=_string_::
++-l+ string, +--host-list+=_string_::
Host to execute actions on. This option may appear an unlimited number
of times.
+
Use this option to specify the host on which this script operates. May
appear multiple times.
-`-p`, `--peers`::
++-p+, +--peers+::
Recursively list all peers a host synchronizes to.
-`-m` number, `--maxlevel`=_number_::
++-m+ number, +--maxlevel+=_number_::
Traverse peers up to this level (4 is a reasonable number). This
option takes an integer number as its argument.
-`-s` string, `--strip`=_string_::
++-s+ string, +--strip+=_string_::
Strip this string from hostnames.
-`-h` string, `--host`=_string_::
++-h+ string, +--host+=_string_::
Specify a single host.
+
_NOTE: THIS OPTION IS DEPRECATED_
diff --git a/scripts/ntptrace/ntptrace-man.txt.in b/scripts/ntptrace/ntptrace-man.txt
similarity index 68%
rename from scripts/ntptrace/ntptrace-man.txt.in
rename to scripts/ntptrace/ntptrace-man.txt
index 12310c0..b7aab9b 100644
--- a/scripts/ntptrace/ntptrace-man.txt.in
+++ b/scripts/ntptrace/ntptrace-man.txt
@@ -4,7 +4,7 @@
== NAME ==
ntptrace - trace peers of an NTP server
- at ../../docs/includes/ntptrace-body.txt@
+include::../../docs/includes/ntptrace-body.txt[]
== EXIT STATUS ==
@@ -13,4 +13,4 @@ One of the following exit values will be returned:
0 (EXIT_SUCCESS)::
Successful program execution.
1 (EXIT_FAILURE)::
- The operation failed or the command syntax was not valid.
+ The operation failed or the invocation was not valid.
diff --git a/ntpfrob/ntpfrob-man.txt.in b/scripts/ntpwait/ntpwait-man.txt
similarity index 67%
rename from ntpfrob/ntpfrob-man.txt.in
rename to scripts/ntpwait/ntpwait-man.txt
index 7430c18..ec463bf 100644
--- a/ntpfrob/ntpfrob-man.txt.in
+++ b/scripts/ntpwait/ntpwait-man.txt
@@ -1,10 +1,10 @@
-= ntprob(8) =
+= ntpwait(8) =
:doctype: manpage
== NAME ==
-{ntpfrob} - frob the clock hardware
+ntpwait - Wait for ntpd to stabilize the system clock
- at ../docs/includes/ntpfrob-body.txt@
+include::../../docs/includes/ntpwait-body.txt[]
== EXIT STATUS ==
@@ -15,5 +15,5 @@ One of the following exit values will be returned:
1 (EXIT_FAILURE)::
The operation failed or the command syntax was not valid.
-
// end
+
diff --git a/scripts/ntpwait/ntpwait-man.txt.in b/scripts/ntpwait/ntpwait-man.txt.in
deleted file mode 100644
index 0ad2a7e..0000000
--- a/scripts/ntpwait/ntpwait-man.txt.in
+++ /dev/null
@@ -1,19 +0,0 @@
-== ntpwait(8) ==
-:doctype: manpage
-
-== NAME ==
-{ntpwait} - Wait for {ntpd} to stabilize the system clock
-
- at ../../docs/includes/ntpwait-body.txt@
-
-== EXIT STATUS ==
-
-One of the following exit values will be returned:
-
-0 (EXIT_SUCCESS)::
- Successful program execution.
-1 (EXIT_FAILURE)::
- The operation failed or the command syntax was not valid.
-
-// end
-
diff --git a/util/ntptime-man.txt.in b/util/ntptime-man.txt
similarity index 56%
rename from util/ntptime-man.txt.in
rename to util/ntptime-man.txt
index d3d5d0e..438cd46 100644
--- a/util/ntptime-man.txt.in
+++ b/util/ntptime-man.txt
@@ -2,9 +2,9 @@
:doctype: manpage
== NAME ==
-{ntptime} - read and set kernel time variables
+ntptime - read and set kernel time variables
- at ../docs/includes/ntptime-body.txt@
+include::../docs/includes/ntptime-body.txt[]
== EXIT STATUS ==
@@ -13,6 +13,6 @@ One of the following exit values will be returned:
0 (EXIT_SUCCESS)::
Successful program execution.
1 (EXIT_FAILURE)::
- The operation failed or the command syntax was not valid.
+ The operation failed or the command invocation was not valid.
// end
diff --git a/wscript b/wscript
index 385a566..b0a9e8e 100644
--- a/wscript
+++ b/wscript
@@ -120,22 +120,23 @@ def build(ctx):
chmod = Utils.O755
)
- subst_files = [
- "ntpkeygen/ntpkeygen-man.txt.in",
- "ntpd/complete.conf.in",
- "ntpd/ntpd-man.txt.in",
- "ntpq/ntpq-man.txt.in",
- "ntpleapfetch/ntpleapfetch.txt.in",
- "scripts/ntpwait/ntpwait-man.txt.in",
- "scripts/ntptrace/ntptrace-man.txt.in",
- "ntpdig/ntpdig-man.txt.in",
- "ntpfrob/ntpfrob-man.txt.in",
- "util/ntptime-man.txt.in",
+ man_sources = [
+ "ntpkeygen/ntpkeygen-man.txt",
+ "ntpd/ntpd-man.txt",
+ "ntpq/ntpq-man.txt",
+ "ntpleapfetch/ntpleapfetch-man.txt",
+ "scripts/ntpwait/ntpwait-man.txt",
+ "scripts/ntpsweep/ntpsweep-man.txt",
+ "scripts/ntptrace/ntptrace-man.txt",
+ "ntpdig/ntpdig-man.txt",
+ "ntpfrob/ntpfrob-man.txt",
+ "util/ntptime-man.txt",
]
- ctx(
- features = "subst",
- source = subst_files,
- target = [x.replace(".in", "") for x in subst_files],
- )
+ //ctx(
+ // features = "subst",
+ // source = subst_files,
+ // target = [x.replace(".in", "") for x in subst_files],
+ //)
+# end
More information about the vc
mailing list