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: Idba84164b90e3d183a20b5eb69cbfe15745e447c
Depends: I6aac73d998c5937894233631e654a160d5623198
Related: SYS#4937, SYS#4910, OS#3036

.gitignore

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

doc/manuals/Makefile.am

@@ -18,8 +18,31 @@ if BUILD_MANUALS
   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
+  VARIANTS = $(NULL)
+
+if ENABLE_SYSMOBTS
+  VARIANTS += sysmo
+endif
+
+if ENABLE_TRX
+  VARIANTS += trx
+endif
+
+if ENABLE_OCTPHY
+  VARIANTS += octphy
+endif
+
+if ENABLE_LC15BTS
+  VARIANTS += lc15
+endif
+
+if ENABLE_OC2GBTS
+  VARIANTS += oc2g
+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-bts
   include $(OSMO_GSM_MANUALS_DIR)/build/Makefile.common.inc

doc/manuals/osmobts-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>hw</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>OsmoBTS VTY Reference</title>
+    <subtitle>@@VARIANT@@</subtitle>
 
     <copyright>
-      <year>2016</year>
+      <year>@@CR_YEAR@@</year>
     </copyright>
 
     <legalnotice>

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

@@ -0,0 +1,37 @@
+DOCBOOKS = $(foreach v,$(VARIANTS),vty/osmobts-$(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/osmobts-%-vty-reference.xml: $(top_srcdir)/src/osmo-bts-% $(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)/osmobts-vty-reference.xml > $@
+
+vty/osmobts-%-vty-reference.xml.inc: $(top_builddir)/src/osmo-bts-*/osmo-bts-% \
+				     $(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-bts-% 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" > $@