doc/manuals: generate XML VTY reference at build-time

Unfortunately, we cannot re-use the existing Makefile rules from:

  $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc

because they do not allow to generate the list of $(DOCBOOKS) from
a template, and require the project to store everything in separate
folders with specific names.  Also, those rules expect that the
target PDFs contain only a single word in their names (for example,
'osmoapp-vty-reference', not 'osmo-app-vty-reference'), while in a
project with multiple similarly named targets this would reduce
readability (imagine 'osmotrxuhd-vty-reference').

Change-Id: I798ea3b7417b8ca3e9c7d50911158c5413526237
Depends: I6aac73d998c5937894233631e654a160d5623198
Related: SYS#4937, SYS#4910

.gitignore

@@ -64,6 +64,9 @@ doc/manuals/*.pdf
 doc/manuals/*__*.png
 doc/manuals/*.check
 doc/manuals/generated/
+doc/manuals/vty/osmotrx-*-vty-reference.xml
+doc/manuals/vty/osmotrx-*-vty-reference.xml.inc.gen
+doc/manuals/vty/osmotrx-*-vty-reference.xml.inc.merged
 doc/manuals/osmomsc-usermanual.xml
 doc/manuals/common
 doc/manuals/build

Makefile.am

@@ -28,13 +28,14 @@ AM_CXXFLAGS = -Wall -pthread
 
 # Order must be preserved
 SUBDIRS = \
-	doc \
 	CommonLibs \
 	GSM \
 	Transceiver52M \
 	contrib \
 	tests \
-	utils
+	utils \
+	doc \
+	$(NULL)
 
 EXTRA_DIST = \
 	LEGAL \

doc/manuals/Makefile.am

@@ -1,6 +1,5 @@
 EXTRA_DIST = osmotrx-usermanual.adoc \
     osmotrx-usermanual-docinfo.xml \
-    osmotrx-vty-reference.xml \
     chapters \
     vty
 
@@ -9,8 +8,24 @@ if BUILD_MANUALS
   ASCIIDOC_DEPS = $(srcdir)/chapters/*.adoc
   include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.asciidoc.inc
 
-  VTY_REFERENCE = osmotrx-vty-reference.xml
-  include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc
+  VARIANTS = $(NULL)
+
+if DEVICE_UHD
+  VARIANTS += uhd
+endif
+if DEVICE_USRP1
+  VARIANTS += usrp1
+endif
+if DEVICE_LMS
+  VARIANTS += lms
+endif
+if DEVICE_IPC
+  VARIANTS += ipc
+endif
+
+  # This is a significantly modified, multi-target adopted copy of
+  # $(OSMO_GSM_MANUALS_DIR)/build/Makefile.vty-reference.inc
+  include $(srcdir)/vty/Makefile.vty-reference.inc
 
   OSMO_REPOSITORY = osmo-trx
   include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc

doc/manuals/vty/Makefile.vty-reference.inc

@@ -0,0 +1,37 @@
+DOCBOOKS = $(foreach v,$(VARIANTS),vty/osmotrx-$(v)-vty-reference.xml)
+DOCBOOKS_DEPS = $(DOCBOOKS) $(addsuffix .inc,$(DOCBOOKS))
+INC_DIR = $(abspath $(builddir)/vty)
+
+include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.docbook.inc
+
+CLEAN_FILES += $(DOCBOOKS_DEPS)
+CLEAN_FILES += $(addsuffix .inc.gen,$(DOCBOOKS))
+CLEAN_FILES += $(addsuffix .inc.merged,$(DOCBOOKS))
+
+$(INC_DIR):
+	mkdir -p $@
+
+vty/osmotrx-%-vty-reference.xml: $(top_builddir)/Transceiver52M/osmo-trx-% $(INC_DIR)
+	sed -e "s|@@GENERATED@@|$@.inc|" \
+	    -e "s|@@VARIANT@@|$(notdir $<)|" \
+	    -e "s|@@REV_NUMBER@@|$(VERSION)|" \
+	    -e "s|@@REV_DATE@@|$(shell date +"%dth %B %Y")|" \
+	    -e "s|@@CR_YEAR@@|$(shell date +"%Y")|" \
+		$(srcdir)/vty/osmotrx-vty-reference.xml > $@
+
+vty/osmotrx-%-vty-reference.xml.inc: $(top_builddir)/Transceiver52M/osmo-trx-% \
+				     $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \
+				     $(OSMO_GSM_MANUALS_DIR)/common/chapters/vty.xml \
+				     $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl \
+				     $(srcdir)/vty/*.xml $(INC_DIR)
+	# a) Invoke osmo-trx-% to generate the list of commands first
+	$< --vty-ref-mode default --vty-ref-xml > "$@.gen"
+	# ... filter garbage potentially printed by libraries to stdout
+	sed -i '/^<vtydoc/,$$!d' "$@.gen"
+	# b) Merge the result of a) with global and local additions
+	$(OSMO_GSM_MANUALS_DIR)/build/vty_reference_combine.sh \
+		$(realpath $(OSMO_GSM_MANUALS_DIR)/merge_doc.xsl) "$@.gen" \
+		$(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \
+		$(srcdir)/vty/*additions*.xml > "$@.merged"
+	# c) Convert the result of b) into a valid docbook
+	xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl "$@.merged" > $@

doc/manuals/vty/osmotrx-vty-reference.xml

@@ -6,7 +6,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 sections-vty     SYSTEM      "generated/docbook_vty.xml"  >
+<!ENTITY sections-vty     SYSTEM      "@@GENERATED@@" >
 ]>
 
 <book>
@@ -18,12 +18,19 @@
             <authorinitials>pe</authorinitials>
             <revremark>Initial</revremark>
         </revision>
+        <revision>
+            <revnumber>v2</revnumber>
+            <date>@@REV_DATE@@</date>
+            <authorinitials>s.f.m.c.</authorinitials>
+            <revremark>Automatic build (@@REV_NUMBER@@)</revremark>
+        </revision>
     </revhistory>
 
     <title>OsmoTRX VTY Reference</title>
+    <subtitle>@@VARIANT@@</subtitle>
 
     <copyright>
-      <year>2018</year>
+      <year>@@CR_YEAR@@</year>
     </copyright>
 
     <legalnotice>