Skip to contentSkip to conversation

ndctl, Documentation: Allow for Makefile variables in Documentation

PATCH In review Vishal Verma 3 participants 3 messages Jan 18, 2019

Subsystems (2)
lore
Share & tools
lore

Vishal Verma

author maintainer
#0 lore raw

PATCH 1/1 ndctl, Documentation: Allow for Makefile variables in Documentation

We were starting to accumulate automake variables such as configureation file paths that were also referenced in Documentation man pages. However, until now, the man pages simply hard coded these paths to their default values. If a distribution were to configure such a path to something other than the default, the man pages would be out of sync with the reality.

Arrange for Makefile variables to be piped into an 'attrs.adoc' target (the variables to be piped in this manner still ahve to be listed explicitly). The different asciidoc(tor) source files can then include attrs.adoc to use these variables.

Finally, convert instances of '/etc/ndctl/monitor.conf' in the monitor documentation to use this new facility.

Cc QI Fuli <[email protected]>
Cc Dave Jiang <[email protected]>
Cc Dan Williams <[email protected]>
---
 Documentation/ndctl/Makefile.am       | 10 +++++++++-
 Documentation/ndctl/ndctl-monitor.txt | 16 ++++++++++------
 2 files changed, 19 insertions(+), 7 deletions(-)
Documentation/ndctl/Makefile.am +9 -1
index a30b139..7e17f20 100644
@@ -51,6 +51,13 @@ man1_MANS = \
 
 CLEANFILES = $(man1_MANS)
 
+.ONESHELL:
+attrs.adoc: $(srcdir)/Makefile.am
+	$(AM_V_GEN) cat <<- EOF >$@
+		:ndctl_monitorconfdir: $(ndctl_monitorconfdir)
+		:ndctl_monitorconf: $(ndctl_monitorconf)
+		EOF
+
 XML_DEPS = \
 	../../version.m4 \
 	Makefile \
@@ -63,7 +70,8 @@ XML_DEPS = \
 	xable-namespace-options.txt \
 	ars-description.txt \
 	labels-description.txt \
-	labels-options.txt
+	labels-options.txt \
+	attrs.adoc
 
 RM ?= rm -f
 
Documentation/ndctl/ndctl-monitor.txt +10 -6
index 363c398..2239f04 100644
@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0
 
+include::attrs.adoc[]
+
 ndctl-monitor(1)
 ================
 
@@ -19,11 +21,13 @@ objects and dumping the json format notifications to syslog, standard
 output or a logfile.
 
 The objects to monitor and smart events to notify can be selected by
-setting options and/or the default configuration file
-(/etc/ndctl/monitor.conf). Both of the values in configuration file
-and in options will work. If there is a conflict, the values in
-options will override the values in configuration file. The changed
-values in configuration file will work after the monitor is restarted.
+setting options and/or the configuration file at
+{ndctl_monitorconfdir}/{ndctl_monitorconf}
+
+Both, the values in configuration file and in options will work. If
+there is a conflict, the values in options will override the values in
+the configuration file. Any updated values in the configuration file will
+take effect only after the monitor process is restarted.
 
 EXAMPLES
 --------
@@ -83,7 +87,7 @@ will not work if "--daemon" is specified.
 -c::
 --config-file=::
 	Provide the config file to use. This overrides the default config
-	typically found in /etc/ndctl/
+	typically found in {ndctl_monitorconfdir}
 
 --daemon::
 	Run a monitor as a daemon.
Signature · 6 lines
2.20.1

_______________________________________________
Linux-nvdimm mailing list
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm
maintainer Reviewed-by on v1 1/1
#1 lore raw
Quoted 12 lines · Vishal Verma

We were starting to accumulate automake variables such as configureation file paths that were also referenced in Documentation man pages. However, until now, the man pages simply hard coded these paths to their default values. If a distribution were to configure such a path to something other than the default, the man pages would be out of sync with the reality.

Arrange for Makefile variables to be piped into an 'attrs.adoc' target (the variables to be piped in this manner still ahve to be listed explicitly). The different asciidoc(tor) source files can then include attrs.adoc to use these variables.

Quoted 7 lines

Finally, convert instances of '/etc/ndctl/monitor.conf' in the monitor documentation to use this new facility.

Cc QI Fuli <[email protected]>
Cc Dave Jiang <[email protected]>
Cc Dan Williams <[email protected]>
Quoted 66 lines
---
 Documentation/ndctl/Makefile.am       | 10 +++++++++-
 Documentation/ndctl/ndctl-monitor.txt | 16 ++++++++++------
 2 files changed, 19 insertions(+), 7 deletions(-)
Documentation/ndctl/Makefile.am +9 -1
index a30b139..7e17f20 100644
@@ -51,6 +51,13 @@ man1_MANS = \
 
 CLEANFILES = $(man1_MANS)
 
+.ONESHELL:
+attrs.adoc: $(srcdir)/Makefile.am
+	$(AM_V_GEN) cat <<- EOF >$@
+		:ndctl_monitorconfdir: $(ndctl_monitorconfdir)
+		:ndctl_monitorconf: $(ndctl_monitorconf)
+		EOF
+
 XML_DEPS = \
 	../../version.m4 \
 	Makefile \
@@ -63,7 +70,8 @@ XML_DEPS = \
 	xable-namespace-options.txt \
 	ars-description.txt \
 	labels-description.txt \
-	labels-options.txt
+	labels-options.txt \
+	attrs.adoc
 
 RM ?= rm -f
 
Documentation/ndctl/ndctl-monitor.txt +9 -5
index 363c398..2239f04 100644
@@ -1,5 +1,7 @@
 // SPDX-License-Identifier: GPL-2.0
 
+include::attrs.adoc[]
+
 ndctl-monitor(1)
 ================
 
@@ -19,11 +21,13 @@ objects and dumping the json format notifications to syslog, standard
 output or a logfile.
 
 The objects to monitor and smart events to notify can be selected by
-setting options and/or the default configuration file
-(/etc/ndctl/monitor.conf). Both of the values in configuration file
-and in options will work. If there is a conflict, the values in
-options will override the values in configuration file. The changed
-values in configuration file will work after the monitor is restarted.
+setting options and/or the configuration file at
+{ndctl_monitorconfdir}/{ndctl_monitorconf}
+
+Both, the values in configuration file and in options will work. If
+there is a conflict, the values in options will override the values in
+the configuration file. Any updated values in the configuration file will
+take effect only after the monitor process is restarted.
 
 EXAMPLES
 --------

Documentation/ndctl/ndctl-monitor.txt will not work if "--daemon" is specified. · line 93

Quoted 8 lines
Documentation/ndctl/ndctl-monitor.txt +1 -1
@@ -83,7 +87,7 @@ will not work if "--daemon" is specified.
 -c::
 --config-file=::
 	Provide the config file to use. This overrides the default config
-	typically found in /etc/ndctl/
+	typically found in {ndctl_monitorconfdir}
 
 --daemon::
 	Run a monitor as a daemon.

_______________________________________________
Linux-nvdimm mailing list
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm

Acked-by on v1 1/1
#2 lore raw
In reply to Vishal Verma
Quoted 13 lines · Vishal Verma

We were starting to accumulate automake variables such as configureation file paths that were also referenced in Documentation man pages. However, until now, the man pages simply hard coded these paths to their default values. If a distribution were to configure such a path to something other than the default, the man pages would be out of sync with the reality.

Arrange for Makefile variables to be piped into an 'attrs.adoc' target (the variables to be piped in this manner still ahve to be listed explicitly). The different asciidoc(tor) source files can then include attrs.adoc to use these variables.

Quoted 7 lines

Finally, convert instances of '/etc/ndctl/monitor.conf' in the monitor documentation to use this new facility.

Cc QI Fuli <[email protected]>
Cc Dave Jiang <[email protected]>
Cc Dan Williams <[email protected]>

Nice!

_______________________________________________
Linux-nvdimm mailing list
[email protected]
https://lists.01.org/mailman/listinfo/linux-nvdimm