build manuals moved here from osmo-gsm-manuals.git

Moved to doc/manuals/, with full commit history, in preceding merge commit.
Now incorporate in the build system.

Build with:

$ autoreconf -fi
$ ./configure --enable-manuals
$ make

Shared files from osmo-gsm-manuals.git are found automatically if
- the repository is checked out in ../osmo-gsm-manuals; or
- if it osmo-gsm-manuals was installed with "make install"; or
- OSMO_GSM_MANUALS_DIR is set.

Related: OS#3385
Change-Id: I728ebb56ade6dda079a0744c4e592284e1bea4f6

9 files changed, 106 insertions, 39 deletions

diff --git a/.gitignore b/.gitignore
index d81bd450..305553ff 100644
--- a/.gitignore
+++ b/.gitignore
@@ -80,3 +80,14 @@ debian/osmo-bts-trx-dbg/
 debian/osmo-bts-trx/
 debian/tmp/
 /tests/power/power_test
+
+# manuals
+doc/manuals/*.html
+doc/manuals/*.svg
+doc/manuals/*.pdf
+doc/manuals/*__*.png
+doc/manuals/*.check
+doc/manuals/generated/
+doc/manuals/osmomsc-usermanual.xml
+doc/manuals/common
+doc/manuals/build
diff --git a/configure.ac b/configure.ac
index 9a8d58f1..e3fefea7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -300,6 +300,48 @@ if test "$enable_oc2g" = "yes"; then
 	CPPFLAGS=$oldCPPFLAGS
 fi
 
+# Generate manuals
+AC_ARG_ENABLE(manuals,
+	[AS_HELP_STRING(
+		[--enable-manuals],
+		[Generate manual PDFs [default=no]],
+	)],
+	[osmo_ac_build_manuals=$enableval], [osmo_ac_build_manuals="no"])
+AM_CONDITIONAL([BUILD_MANUALS], [test x"$osmo_ac_build_manuals" = x"yes"])
+AC_ARG_VAR(OSMO_GSM_MANUALS_DIR, [path to common osmo-gsm-manuals files, overriding pkg-config and "../osmo-gsm-manuals"
+	fallback])
+if test x"$osmo_ac_build_manuals" = x"yes"
+then
+	# Find OSMO_GSM_MANUALS_DIR (env, pkg-conf, fallback)
+	if test -n "$OSMO_GSM_MANUALS_DIR"; then
+		echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from env)"
+	else
+		OSMO_GSM_MANUALS_DIR="$($PKG_CONFIG osmo-gsm-manuals --variable=osmogsmmanualsdir 2>/dev/null)"
+		if test -n "$OSMO_GSM_MANUALS_DIR"; then
+			echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (from pkg-conf)"
+		else
+			OSMO_GSM_MANUALS_DIR="../osmo-gsm-manuals"
+			echo "checking for OSMO_GSM_MANUALS_DIR... $OSMO_GSM_MANUALS_DIR (fallback)"
+		fi
+	fi
+	if ! test -d "$OSMO_GSM_MANUALS_DIR"; then
+		AC_MSG_ERROR("OSMO_GSM_MANUALS_DIR does not exist! Install osmo-gsm-manuals or set OSMO_GSM_MANUALS_DIR.")
+	fi
+
+	# Find and run check-depends
+	CHECK_DEPENDS="$OSMO_GSM_MANUALS_DIR/check-depends.sh"
+	if ! test -x "$CHECK_DEPENDS"; then
+		CHECK_DEPENDS="osmo-gsm-manuals-check-depends"
+	fi
+	if ! $CHECK_DEPENDS; then
+		AC_MSG_ERROR("missing dependencies for --enable-manuals")
+	fi
+
+	# Put in Makefile with absolute path
+	OSMO_GSM_MANUALS_DIR="$(realpath "$OSMO_GSM_MANUALS_DIR")"
+	AC_SUBST([OSMO_GSM_MANUALS_DIR])
+fi
+
 # https://www.freedesktop.org/software/systemd/man/daemon.html
 AC_ARG_WITH([systemdsystemunitdir],
      [AS_HELP_STRING([--with-systemdsystemunitdir=DIR], [Directory for systemd service files])],,
@@ -345,6 +387,7 @@ AC_OUTPUT(
     tests/meas/Makefile
     doc/Makefile
     doc/examples/Makefile
+    doc/manuals/Makefile
     contrib/Makefile
     contrib/systemd/Makefile
     Makefile)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1d42b0aa..2f308154 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,3 +1,4 @@
 SUBDIRS = \
         examples \
+	manuals \
         $(NULL)
diff --git a/doc/manuals/Makefile b/doc/manuals/Makefile
deleted file mode 100644
index e1ff2147..00000000
--- a/doc/manuals/Makefile
+++ /dev/null
@@ -1,12 +0,0 @@
-TOPDIR = ..
-
-ASCIIDOC = osmobts-usermanual.adoc osmobts-abis.adoc rtp-amr.adoc
-include $(TOPDIR)/build/Makefile.asciidoc.inc
-osmobts-usermanual.pdf: chapters/*.adoc
-osmobts-abis.pdf: abis/*.adoc abis/*.msc
-rtp-amr.pdf: dtx.dot
-
-VTY_REFERENCE = osmobts-vty-reference.xml
-include $(TOPDIR)/build/Makefile.vty-reference.inc
-
-include $(TOPDIR)/build/Makefile.common.inc
diff --git a/doc/manuals/Makefile.am b/doc/manuals/Makefile.am
new file mode 100644
index 00000000..90fff57e
--- /dev/null
+++ b/doc/manuals/Makefile.am
@@ -0,0 +1,24 @@
+EXTRA_DIST = dtx.dot \
+    osmobts-abis.adoc \
+    osmobts-abis-docinfo.xml \
+    osmobts-usermanual.adoc \
+    osmobts-usermanual-docinfo.xml \
+    osmobts-vty-reference.xml \
+    rtp-amr.adoc \
+    rtp-amr-docinfo.xml \
+    abis \
+    chapters \
+    vty
+
+if BUILD_MANUALS
+  ASCIIDOC = osmobts-usermanual.adoc osmobts-abis.adoc rtp-amr.adoc
+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
+  osmobts-usermanual.pdf: $(srcdir)/chapters/*.adoc
+  osmobts-abis.pdf: $(srcdir)/abis/*.adoc $(srcdir)/abis/*.msc
+  rtp-amr.pdf: $(srcdir)/dtx.dot
+
+  VTY_REFERENCE = osmobts-vty-reference.xml
+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc
+
+  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc
+endif
diff --git a/doc/manuals/osmobts-abis.adoc b/doc/manuals/osmobts-abis.adoc
index 1e02414d..857b4bfb 100644
--- a/doc/manuals/osmobts-abis.adoc
+++ b/doc/manuals/osmobts-abis.adoc
@@ -64,7 +64,7 @@ established.
 .Overview of A-bis connection establishment
 ["mscgen"]
 ----
-include::abis/abis-startup.msc[]
+include::{srcdir}/abis/abis-startup.msc[]
 ----
 
 === Identities
@@ -77,16 +77,16 @@ parts:
 * The BTS number at the site
 * The TRX number within the BTS
 
-include::abis/ipa.adoc[]
+include::{srcdir}/abis/ipa.adoc[]
 
-include::abis/oml.adoc[]
+include::{srcdir}/abis/oml.adoc[]
 
-include::abis/rsl.adoc[]
+include::{srcdir}/abis/rsl.adoc[]
 
-include::abis/rtp.adoc[]
+include::{srcdir}/abis/rtp.adoc[]
 
-include::../common/chapters/port_numbers.adoc[]
+include::./common/chapters/port_numbers.adoc[]
 
-include::../common/chapters/glossary.adoc[]
+include::./common/chapters/glossary.adoc[]
 
-include::../common/chapters/gfdl.adoc[]
+include::./common/chapters/gfdl.adoc[]
diff --git a/doc/manuals/osmobts-usermanual.adoc b/doc/manuals/osmobts-usermanual.adoc
index 07f88e28..40db72b8 100644
--- a/doc/manuals/osmobts-usermanual.adoc
+++ b/doc/manuals/osmobts-usermanual.adoc
@@ -4,36 +4,36 @@ OsmoBTS User Manual
 ===================
 Harald Welte <hwelte@sysmocom.de>
 
-include::../common/chapters/preface.adoc[]
+include::./common/chapters/preface.adoc[]
 
-include::chapters/overview.adoc[]
+include::{srcdir}/chapters/overview.adoc[]
 
-include::../common/chapters/abis.adoc[]
+include::./common/chapters/abis.adoc[]
 
-include::chapters/interfaces.adoc[]
+include::{srcdir}/chapters/interfaces.adoc[]
 
-include::chapters/control.adoc[]
+include::{srcdir}/chapters/control.adoc[]
 
-include::../common/chapters/vty.adoc[]
+include::./common/chapters/vty.adoc[]
 
-include::../common/chapters/logging.adoc[]
+include::./common/chapters/logging.adoc[]
 
-include::chapters/configuration.adoc[]
+include::{srcdir}/chapters/configuration.adoc[]
 
-include::chapters/dynamic-timeslots.adoc[]
+include::{srcdir}/chapters/dynamic-timeslots.adoc[]
 
-include::chapters/bts-models.adoc[]
+include::{srcdir}/chapters/bts-models.adoc[]
 
-include::chapters/architecture.adoc[]
+include::{srcdir}/chapters/architecture.adoc[]
 
-include::../common/chapters/trx_if.adoc[]
+include::./common/chapters/trx_if.adoc[]
 
-include::../common/chapters/control_if.adoc[]
+include::./common/chapters/control_if.adoc[]
 
-include::../common/chapters/port_numbers.adoc[]
+include::./common/chapters/port_numbers.adoc[]
 
-include::../common/chapters/bibliography.adoc[]
+include::./common/chapters/bibliography.adoc[]
 
-include::../common/chapters/glossary.adoc[]
+include::./common/chapters/glossary.adoc[]
 
-include::../common/chapters/gfdl.adoc[]
+include::./common/chapters/gfdl.adoc[]
diff --git a/doc/manuals/osmobts-vty-reference.xml b/doc/manuals/osmobts-vty-reference.xml
index f4048434..b7c8a596 100644
--- a/doc/manuals/osmobts-vty-reference.xml
+++ b/doc/manuals/osmobts-vty-reference.xml
@@ -5,7 +5,7 @@
 -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML 5.0//EN"
 "http://docbook.org/xml/5.0/dtd/docbook.dtd" [
-<!ENTITY chapter-vty      SYSTEM      "../common/chapters/vty.xml" >
+<!ENTITY chapter-vty      SYSTEM      "./common/chapters/vty.xml" >
 <!ENTITY sections-vty     SYSTEM      "generated/docbook_vty.xml"  >
 ]>
 
diff --git a/doc/manuals/rtp-amr.adoc b/doc/manuals/rtp-amr.adoc
index 4da2e1b3..5a36aeab 100644
--- a/doc/manuals/rtp-amr.adoc
+++ b/doc/manuals/rtp-amr.adoc
@@ -1335,7 +1335,7 @@ There is FSM implementing all the necessary states and transitions for DTX DL.
 [[dtx_dl_fsm]]
 [graphviz]
 ----
-include::dtx.dot[]
+include::{srcdir}/dtx.dot[]
 ----
 
 The idea is that each state corresponds to the particular message type which have to be send to L1 next while state transition happens on incoming events like FACCH or Voice frames. There are 3 different classes of of events driving this FSM: