From 6dd00d876e2b947e070f776f90fbb8305a237d21 Mon Sep 17 00:00:00 2001
From: Daniel Willmann <dwillmann@sysmocom.de>
Date: Thu, 27 Sep 2018 17:20:44 +0200
Subject: osmo-config-merge: Add manual page

Change-Id: Ifaa5afe28779a805764caf76a89efb0a3169942e
---
 .gitignore                 |  1 +
 Makefile.am                |  2 +-
 configure.ac               | 14 ++++++++++
 man/Makefile.am            | 15 +++++++++++
 man/osmo-config-merge.adoc | 64 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 95 insertions(+), 1 deletion(-)
 create mode 100644 man/Makefile.am
 create mode 100644 man/osmo-config-merge.adoc

diff --git a/.gitignore b/.gitignore
index 451c8831..cb2ce683 100644
--- a/.gitignore
+++ b/.gitignore
@@ -81,6 +81,7 @@ doc/gsm
 doc/gb
 doc/html.tar
 doc/*.tag
+man/*.8
 tags
 
 src/crc*gen.c
diff --git a/Makefile.am b/Makefile.am
index de5eb35d..745d482c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,7 +1,7 @@
 ACLOCAL_AMFLAGS = -I m4
 
 AM_CPPFLAGS = $(all_includes) -I$(top_srcdir)/include
-SUBDIRS = include src src/vty src/codec src/gsm src/coding src/gb src/ctrl src/sim src/pseudotalloc utils tests
+SUBDIRS = include src src/vty src/codec src/gsm src/coding src/gb src/ctrl src/sim src/pseudotalloc utils tests man
 
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libosmocore.pc libosmocodec.pc libosmovty.pc libosmogsm.pc \
diff --git a/configure.ac b/configure.ac
index bc3358a0..529aad1d 100644
--- a/configure.ac
+++ b/configure.ac
@@ -77,6 +77,19 @@ AC_ARG_ENABLE(doxygen,
 AC_PATH_PROG(DOXYGEN,doxygen,false)
 AM_CONDITIONAL(HAVE_DOXYGEN, test $DOXYGEN != false && test "x$doxygen" = "xyes")
 
+AC_ARG_ENABLE([man-doc],
+	      [AS_HELP_STRING([--disable-man-doc], [Disable man page documentation])],
+	      [ BUILD_MAN=$enableval ], [ BUILD_MAN="yes" ])
+
+AS_IF([test "x$BUILD_MAN" = "xyes"], [
+      AC_CHECK_PROG(A2X, [a2x], [yes])
+      AS_IF([test "$A2X" != "yes"],
+	    [AC_MSG_ERROR([a2x not found, please install asciidoc or use the
+	     option --disable-man-doc])])
+])
+AM_CONDITIONAL(BUILD_MAN, test "x$BUILD_MAN" = "xyes")
+AC_SUBST(BUILD_MAN)
+
 # check for syscal fallback on glibc < 2.25 - can be removed once glibc version requirement is bumped
 AC_CHECK_DECLS([SYS_getrandom], [], [], [[#include <sys/syscall.h>]])
 
@@ -370,6 +383,7 @@ AC_OUTPUT(
 	libosmoctrl.pc
 	libosmosim.pc
 	include/Makefile
+	man/Makefile
 	src/Makefile
 	src/vty/Makefile
 	src/codec/Makefile
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 00000000..b2877148
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1,15 @@
+if BUILD_MAN
+man_MANS =  osmo-config-merge.8
+endif
+
+ASCIIDOCS = osmo-config-merge.adoc
+
+A2X_OPTS_MANPAGE = --doctype manpage --format manpage -D ${builddir}
+
+%.8 : %.adoc
+		a2x ${A2X_OPTS_MANPAGE} $<
+
+EXTRA_DIST = ${ASCIIDOCS}
+
+CLEANFILES = \
+	     osmo-config-merge.8
diff --git a/man/osmo-config-merge.adoc b/man/osmo-config-merge.adoc
new file mode 100644
index 00000000..205fb502
--- /dev/null
+++ b/man/osmo-config-merge.adoc
@@ -0,0 +1,64 @@
+osmo-config-merge(8)
+=====================
+
+NAME
+----
+osmo-config-merge - Merge osmocom config snippets into an existing config
+
+SYNOPSIS
+--------
+[verse]
+*osmo-config-merge* <config-file> <config-patch> [--debug]
+
+DESCRIPTION
+-----------
+This utility allows you to merge an incremental config "patch"
+into an osmocom-style config file.
+
+The patch file follows the same syntax as the original config file.
+
+It works by appending the leaf nodes of the patch file to the respective
+nodes of the input config file.
+
+This process allows configuration file changes/updates to be performed
+in a more stable/reliable way than by means of (unified) diff files,
+as they break every time the context lines break.
+
+osmo-config-merge doesn't suffer from this problem, as it understands
+the tree-like nature of VTY config files.
+
+The resulting config is printed to stdout.
+
+NOTE: This only works with configuration files that have proper
+indenting, i.e. every level in the hierarchy must be indented excatly
+one character, not multiple.
+
+OPTIONS
+-------
+*--debug*::
+	Show debugging output when parsing the config tree. Needs to be the last argument.
+
+EXAMPLE USAGE
+-------------
+[verse]
+$ osmo-config-merge osmo-msc.cfg.base osmo-msc_change_network.cfg > osmo-msc.cfg
+
+EXIT STATUS
+-----------
+Exit status is 0 if the command was successful, and 1 in case of a
+wrong/missing argument. If the tool detects an error in the patch file the
+exit status is 2.
+
+SEE ALSO
+--------
+The official Osmocom documentation including the VTY config refernce can be
+found at: http://ftp.osmocom.org/docs/latest/
+
+The Osmocom wiki is located at: http://projects.osmocom.org/
+
+
+AUTHORS
+-------
+osmo-config-merge was written by Harald Welte.
+
+The man page was written by Daniel Willmann.
-- 
cgit v1.2.3