[MERGED] osmo-gsm-manuals[master]: refactor Makefile build rules, don't use the FORCE

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

Neels Hofmeyr gerrit-no-reply at lists.osmocom.org
Wed Oct 25 16:51:56 UTC 2017


Neels Hofmeyr has submitted this change and it was merged.

Change subject: refactor Makefile build rules, don't use the FORCE
......................................................................


refactor Makefile build rules, don't use the FORCE

The initial goal was to make sure we don't have overall FORCE rules causing
unnecessary rebuilds -- annoying while writing documentation. As I looked
through possible dependencies, I finally understood what's going on here.

Remove code dup and nicely sort which belongs where in build/Makefile.*.inc. In
each, describe in a top comment how to use it, and also unify how they are
used:

- Rename Makefile.inc to Makefile.docbook.inc and refactor
- Add Makefile.vty-reference.inc
- Add Makefile.common.inc

Make sure that we accurately pick up all dependencies.

Drop use of the macro called 'command', that silenced the actual command lines
invoked and replaced them with short strings: it obscures what is actually
going on and makes the Makefiles hard to read and understand.

Each manual's makefile is greatly reduced to few definitions and a Makefile
include, e.g. one for asciidoc, one for VTY reference.

Move common/bsc_vty_additions.xml to OsmoBSC/vty/libbsc_vty_additions.xml, link
from OsmoNITB. It applies only to OsmoBSC and OsmoNITB.

Add a script that combines a VTY reference file with *all* additions files
found in a manual's vty/ dir. Call this from Makefile.vty-reference.inc.

Change-Id: I9758e04162a480e28c7dc83475b514cf7fd25ec0
---
M OsmoBSC/Makefile
R OsmoBSC/vty/libbsc_vty_additions.xml
M OsmoBTS/Makefile
M OsmoGGSN/Makefile
M OsmoGSMTester/Makefile
M OsmoHLR/Makefile
M OsmoMGCP/Makefile
M OsmoMSC/Makefile
M OsmoNAT/Makefile
M OsmoNITB/Makefile
A OsmoNITB/vty/bsc_vty_additions.xml
M OsmoPCU/Makefile
M OsmoSGSN/Makefile
M build/Makefile.asciidoc.inc
A build/Makefile.common.inc
A build/Makefile.docbook.inc
D build/Makefile.inc
A build/Makefile.vty-reference.inc
A build/vty_reference_combine.sh
19 files changed, 206 insertions(+), 443 deletions(-)

Approvals:
  Harald Welte: Looks good to me, approved
  Jenkins Builder: Verified



diff --git a/OsmoBSC/Makefile b/OsmoBSC/Makefile
index 35f50da..1533482 100644
--- a/OsmoBSC/Makefile
+++ b/OsmoBSC/Makefile
@@ -1,54 +1,11 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-
-EXTRA_DEPS = gen-bsc-vty-docbook
-
-topdir = .
-bsc_reference = $(topdir)/osmobsc-vty-reference.xml
-manuals = $(bsc_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmobsc-usermanual osmux-reference aoip-mgw-options
-
+ASCIIDOC = osmobsc-usermanual.adoc osmux-reference.adoc aoip-mgw-options.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
-
 osmobsc-usermanual.pdf: chapters/*.adoc
-osmux-reference.pdf: osmux-reference.adoc
-aoip-mgw-options.pdf: aoip-mgw-options.adoc
+aoip-mgw-options.pdf: aoip-mgw-options.adoc mgw/*.msc
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmobsc-usermanual__*.png
-	-rm osmobsc-usermanual__*.svg
-	-rm osmobsc-usermanual*.check
-	-rm osmux-reference*.check
-	-rm aoip-mgw-options*.png
-	-rm aoip-mgw-options*.svg
-	-rm aoip-mgw-options*.check
-	-rm osmux-reference__*.svg
-	-rm osmux-reference__*.png
-	-rm osmux-reference__*.check
+VTY_REFERENCE = osmobsc-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-gen-bsc-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/bsc_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/../common/bsc_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging Common BSC VTY)
-	$(call command,xsltproc -o generated/combined3.xml \
-		--stringparam with $(PWD)/vty/bsc_vty_additions.xml \
-		$(MERGE_DOC) generated/combined2.xml, \
-		XSLTPROC,Merging BSC VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting BSC VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/common/bsc_vty_additions.xml b/OsmoBSC/vty/libbsc_vty_additions.xml
similarity index 100%
rename from common/bsc_vty_additions.xml
rename to OsmoBSC/vty/libbsc_vty_additions.xml
diff --git a/OsmoBTS/Makefile b/OsmoBTS/Makefile
index 58df0e3..e1ff214 100644
--- a/OsmoBTS/Makefile
+++ b/OsmoBTS/Makefile
@@ -1,50 +1,12 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-EXTRA_DEPS = gen-bts-vty-docbook
-
-topdir = .
-bts_reference = $(topdir)/osmobts-vty-reference.xml
-manuals = $(bts_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmobts-usermanual osmobts-abis rtp-amr
-
+ASCIIDOC = osmobts-usermanual.adoc osmobts-abis.adoc rtp-amr.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
-
-osmobts-abis.pdf: abis/*.adoc abis/*.msc
 osmobts-usermanual.pdf: chapters/*.adoc
+osmobts-abis.pdf: abis/*.adoc abis/*.msc
+rtp-amr.pdf: dtx.dot
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmobts-abis__*.png
-	-rm osmobts-abis__*.svg
-	-rm rtp-amr__*.png
-	-rm rtp-amr__*.svg
-	-rm osmobts-usermanual__*.png
-	-rm osmobts-usermanual__*.svg
-	-rm osmobts-abis*.check
-	-rm osmobts-usermanual*.check
+VTY_REFERENCE = osmobts-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-gen-bts-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/bts_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/../common/ns_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging Common NS VTY)
-	$(call command,xsltproc -o generated/combined3.xml \
-		--stringparam with $(PWD)/vty/bts_vty_additions.xml \
-		$(MERGE_DOC) generated/combined2.xml, \
-		XSLTPROC,Merging BTS VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting BTS VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoGGSN/Makefile b/OsmoGGSN/Makefile
index 2dfedb2..e809632 100644
--- a/OsmoGGSN/Makefile
+++ b/OsmoGGSN/Makefile
@@ -1,39 +1,10 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-EXTRA_DEPS = gen-ggsn-vty-docbook
-
-topdir = .
-ggsn_reference = $(topdir)/osmoggsn-vty-reference.xml
-manuals = $(ggsn_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmoggsn-usermanual
-
+ASCIIDOC = osmoggsn-usermanual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
 
-osmoggsn-usermanual.pdf: chapters/*.adoc
+VTY_REFERENCE = osmoggsn-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmoggsn-usermanual__*.svg osmoggsn-usermanual__*.png
-	-rm osmoggsn-usermanual.check
-
-gen-ggsn-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/ggsn_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/vty/ggsn_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging GGSN VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined2.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting GGSN VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoGSMTester/Makefile b/OsmoGSMTester/Makefile
index 79d414f..43c5a37 100644
--- a/OsmoGSMTester/Makefile
+++ b/OsmoGSMTester/Makefile
@@ -1,12 +1,7 @@
-TOPDIR := ..
-ASCIIDOCS := osmo-gsm-tester-manual
+TOPDIR = ..
 
+ASCIIDOC = osmo-gsm-tester-manual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
 
-osmo-gsm-tester-manual.pdf: chapters/*.adoc
-
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmo-gsm-tester-manual__*.svg
-	-rm osmo-gsm-tester-manual__*.png
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoHLR/Makefile b/OsmoHLR/Makefile
index eba5fa3..a9dc393 100644
--- a/OsmoHLR/Makefile
+++ b/OsmoHLR/Makefile
@@ -1,42 +1,10 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-topdir = .
-hlr_reference = $(topdir)/osmohlr-vty-reference.xml
-manuals = $(hlr_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmohlr-usermanual
-
+ASCIIDOC = osmohlr-usermanual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc *.vty *.ctrl
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
 
-osmohlr-usermanual.pdf: chapters/*.adoc generated/docbook_vty.xml
+VTY_REFERENCE = osmohlr-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmohlr-usermanual__*.svg
-	-rm osmohlr-usermanual__*.png
-	-rm osmohlr-usermanual.check
-
-generated/docbook_vty.xml: osmohlr-vty-reference.xml vty/*xml ../common/vty_additions.xml ../vty_reference.xsl
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/hlr_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/../common/bsc_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging Common BSC VTY)
-	$(call command,xsltproc -o generated/combined3.xml \
-		--stringparam with $(PWD)/vty/hlr_vty_additions.xml \
-		$(MERGE_DOC) generated/combined2.xml, \
-		XSLTPROC,Merging HLR VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting HLR VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoMGCP/Makefile b/OsmoMGCP/Makefile
index 9aff12b..e2a5e37 100644
--- a/OsmoMGCP/Makefile
+++ b/OsmoMGCP/Makefile
@@ -1,31 +1,6 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-EXTRA_DEPS = gen-mgcp-vty-docbook
+VTY_REFERENCE = osmomgcp-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-topdir = .
-mgcp_reference = $(topdir)/osmomgcp-vty-reference.xml
-manuals = $(mgcp_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-include ../build/Makefile.inc
-
-clean:
-	-rm -rf $(cleanfiles)
-
-gen-mgcp-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/mgcp_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/vty/mgcp_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging MGCP VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined2.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting MGCP VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoMSC/Makefile b/OsmoMSC/Makefile
index febf7d1..c9edcef 100644
--- a/OsmoMSC/Makefile
+++ b/OsmoMSC/Makefile
@@ -1,42 +1,10 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-topdir = .
-msc_reference = $(topdir)/osmomsc-vty-reference.xml
-manuals = $(msc_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmomsc-usermanual
-
+ASCIIDOC = osmomsc-usermanual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
 
-osmomsc-usermanual.pdf: chapters/*.adoc generated/docbook_vty.xml
+VTY_REFERENCE = osmomsc-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmomsc-usermanual__*.svg
-	-rm osmomsc-usermanual__*.png
-	-rm osmomsc-usermanual.check
-
-generated/docbook_vty.xml: osmomsc-vty-reference.xml vty/*xml ../common/vty_additions.xml ../vty_reference.xsl
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/msc_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/../common/bsc_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging Common BSC VTY)
-	$(call command,xsltproc -o generated/combined3.xml \
-		--stringparam with $(PWD)/vty/msc_vty_additions.xml \
-		$(MERGE_DOC) generated/combined2.xml, \
-		XSLTPROC,Merging MSC VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting MSC VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoNAT/Makefile b/OsmoNAT/Makefile
index d7302e6..fde7132 100644
--- a/OsmoNAT/Makefile
+++ b/OsmoNAT/Makefile
@@ -1,31 +1,6 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-EXTRA_DEPS = gen-nat-vty-docbook
+VTY_REFERENCE = osmonat-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-topdir = .
-nat_reference = $(topdir)/osmonat-vty-reference.xml
-manuals = $(nat_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-include ../build/Makefile.inc
-
-clean:
-	-rm -rf $(cleanfiles)
-
-gen-nat-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/nat_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/vty/nat_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging NAT VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined2.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting NAT VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoNITB/Makefile b/OsmoNITB/Makefile
index 99cd317..0cd260d 100644
--- a/OsmoNITB/Makefile
+++ b/OsmoNITB/Makefile
@@ -1,44 +1,10 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-EXTRA_DEPS = gen-nitb-vty-docbook
-
-topdir = .
-nitb_reference = $(topdir)/osmonitb-vty-reference.xml
-manuals = $(nitb_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmonitb-usermanual
-
+ASCIIDOC = osmonitb-usermanual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
 
-osmonitb-usermanual.pdf: chapters/*.adoc
+VTY_REFERENCE = osmonitb-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmonitb-usermanual__*.svg
-	-rm osmonitb-usermanual__*.png
-	-rm osmonitb-usermanual.check
-
-gen-nitb-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/nitb_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/../common/bsc_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging Common BSC VTY)
-	$(call command,xsltproc -o generated/combined3.xml \
-		--stringparam with $(PWD)/vty/nitb_vty_additions.xml \
-		$(MERGE_DOC) generated/combined2.xml, \
-		XSLTPROC,Merging NITB VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting NITB VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoNITB/vty/bsc_vty_additions.xml b/OsmoNITB/vty/bsc_vty_additions.xml
new file mode 120000
index 0000000..5def5f1
--- /dev/null
+++ b/OsmoNITB/vty/bsc_vty_additions.xml
@@ -0,0 +1 @@
+../../OsmoBSC/vty/bsc_vty_additions.xml
\ No newline at end of file
diff --git a/OsmoPCU/Makefile b/OsmoPCU/Makefile
index a83b909..7a1acc0 100644
--- a/OsmoPCU/Makefile
+++ b/OsmoPCU/Makefile
@@ -1,45 +1,11 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-EXTRA_DEPS = gen-vty-docbook
-
-topdir = .
-pcu_reference = $(topdir)/osmopcu-vty-reference.xml
-manuals = $(bts_manual) $(pcu_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmopcu-usermanual osmopcu-gb
-
+ASCIIDOC = osmopcu-usermanual.adoc osmopcu-gb.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
-
 osmopcu-gb.pdf: gb/*.adoc gb/*.msc
 osmopcu-usermanual.pdf: chapters/*.adoc
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm -rf gen-vty-docbook
-	-rm osmopcu-usermanual__*.png
-	-rm osmopcu-usermanual__*.svg
-	-rm osmopcu-usermanual.check
+VTY_REFERENCE = osmopcu-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-gen-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/osmo-pcu_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/vty/osmo-pcu_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging PCU VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined2.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting PCU VTY to DocBook)
-
-
-
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/OsmoSGSN/Makefile b/OsmoSGSN/Makefile
index 6f7d28d..baa1a49 100644
--- a/OsmoSGSN/Makefile
+++ b/OsmoSGSN/Makefile
@@ -1,43 +1,10 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
+TOPDIR = ..
 
-EXTRA_DEPS = gen-sgsn-vty-docbook
-
-topdir = .
-sgsn_reference = $(topdir)/osmosgsn-vty-reference.xml
-manuals = $(sgsn_reference)
-# types = pdf txt rtf ps xhtml html man tex texi dvi
-# types = pdf txt
-types = $(docbooktotypes)
-docbooktotypes = pdf
-# htmlcssfile =
-# htmlcss =
-
-TOPDIR := ..
-ASCIIDOCS := osmosgsn-usermanual
-
+ASCIIDOC = osmosgsn-usermanual.adoc
+ASCIIDOC_DEPS = chapters/*.adoc
 include $(TOPDIR)/build/Makefile.asciidoc.inc
-include $(TOPDIR)/build/Makefile.inc
 
-osmosgsn-usermanual.pdf: chapters/*.adoc
+VTY_REFERENCE = osmosgsn-vty-reference.xml
+include $(TOPDIR)/build/Makefile.vty-reference.inc
 
-clean:
-	-rm -rf $(cleanfiles)
-	-rm osmosgsn-usermanual__*.svg osmosgsn-usermanual__*.png
-	-rm osmosgsn-usermanual.check
-
-gen-sgsn-vty-docbook: FORCE
-	$(call command,xsltproc -o generated/combined1.xml \
-		--stringparam with $(PWD)/../common/vty_additions.xml \
-		$(MERGE_DOC) vty/sgsn_vty_reference.xml, \
-		XSLTPROC,Merging Common VTY)
-	$(call command,xsltproc -o generated/combined2.xml \
-		--stringparam with $(PWD)/../common/ns_vty_additions.xml \
-		$(MERGE_DOC) generated/combined1.xml, \
-		XSLTPROC,Merging Common NS VTY)
-	$(call command,xsltproc -o generated/combined3.xml \
-		--stringparam with $(PWD)/vty/sgsn_vty_additions.xml \
-		$(MERGE_DOC) generated/combined2.xml, \
-		XSLTPROC,Merging SGSN VTY)
-	$(call command,xsltproc ../vty_reference.xsl generated/combined3.xml > generated/docbook_vty.xml, \
-		XSLTPROC,Converting SGSN VTY to DocBook)
+include $(TOPDIR)/build/Makefile.common.inc
diff --git a/build/Makefile.asciidoc.inc b/build/Makefile.asciidoc.inc
index e088624..a28a5bb 100644
--- a/build/Makefile.asciidoc.inc
+++ b/build/Makefile.asciidoc.inc
@@ -1,19 +1,38 @@
+# USAGE:
+#
+# - define 'TOPDIR' to point at the git root,
+# - define in 'ASCIIDOC' all root .adoc files,
+# - optionally define in 'ASCIIDOC_DEPS' all dependencies common to all .adocs,
+# - include this file,
+# - optionally define further dependencies for individual .pdf targets.
+#
+# e.g.
+#
+#     TOPDIR = ..
+#     ASCIIDOC = osmo_yada.adoc osmo_moo.adoc
+#     ASCIIDOC_DEPS = for_all/*.adoc
+#     include $(TOPDIR)/build/Makefile.asciidoc.inc
+#     osmo_yada.pdf: yada/*.adoc yada/*.msc
+
 BUILDDIR = $(TOPDIR)/build
 
 GIT_VERSION := $(shell git describe --abbrev=4 --dirty --always --tags)
 GIT_DATE := $(shell $(TOPDIR)/build/unix-time-to-fmt.py `git log -n 1 "--pretty=%at" ../.`)
 
 # prepend the document name with the version numbe suffix
-#DOCS_VER = $(foreach P, $(ASCIIDOCS), $(P)-v$(shell xmllint --recover --xpath "//revnumber[position()=last()]/text()" $(P)-docinfo.xml 2>/dev/null))
+#DOCS_VER = $(foreach P, $(ASCIIDOC_NAME), $(P)-v$(shell xmllint --recover --xpath "//revnumber[position()=last()]/text()" $(P)-docinfo.xml 2>/dev/null))
 #PDFS = $(DOCS_VER:%=%.pdf)
 
 # generate list of PDFs that we're supposed to render
-ASCIIDOCPDFS = $(ASCIIDOCS:%=%.pdf)
-ASCIIDOC_CHECKS = $(ASCIIDOCS:%=%.check)
+ASCIIDOC_NAME = $(patsubst %.adoc,%,$(ASCIIDOC))
+ASCIIDOC_PDF = $(ASCIIDOC_NAME:%=%.pdf)
+ASCIIDOC_CHECKS = $(ASCIIDOC_NAME:%=%.check)
 
 ASCIIDOCSTYLE ?= $(BUILDDIR)/custom-dblatex.sty
 
-cleanfiles += $(ASCIIDOCPDFS)
+CLEAN_FILES += $(ASCIIDOC_NAME:%=%__*.png) $(ASCIIDOC_NAME:%=%__*.svg) $(ASCIIDOC_CHECKS)
+CLEAN_FILES += $(ASCIIDOC_PDF)
+UPLOAD_FILES += $(ASCIIDOC_PDF)
 
 ASCIIDOC_OPTS := -f $(BUILDDIR)/mscgen-filter.conf -f $(BUILDDIR)/diag-filter.conf -f $(BUILDDIR)/docinfo-releaseinfo.conf -f $(BUILDDIR)/python2-filter.conf
 DBLATEX_OPTS := -s $(ASCIIDOCSTYLE) -P draft.mode=yes -P draft.watermark=0
@@ -27,9 +46,13 @@
 A2X_OPTS := -L --asciidoc-opts="$(ASCIIDOC_OPTS)" --dblatex-opts="$(DBLATEX_OPTS)" -a docinfo -a revnumber="$(REVNUMBER)" -a revdate="$(GIT_DATE)"
 
 
-all: $(ASCIIDOCPDFS)
+all: $(ASCIIDOC_PDF)
 
-$(ASCIIDOCPDFS): %.pdf: %.adoc %-docinfo.xml $(ASCIIDOCSTYLE) $(TOPDIR)/common/chapters/*.adoc
+$(ASCIIDOC_PDF): %.pdf: %.adoc %-docinfo.xml \
+		$(ASCIIDOC_DEPS) \
+		$(ASCIIDOCSTYLE) \
+		$(TOPDIR)/common/*/*.adoc \
+		$(TOPDIR)/common/images/*
 	@test -n "$(BUILD_RELEASE)" && echo -e "\n\n\
 	  NOTE: TO REMOVE DRAFT MODE, YOU NEED TO EDIT build/custom-dblatex.sty\n\
 	        and remove three lines starting with '% \"DRAFT\" on first page'\n" \
diff --git a/build/Makefile.common.inc b/build/Makefile.common.inc
new file mode 100644
index 0000000..e624b5f
--- /dev/null
+++ b/build/Makefile.common.inc
@@ -0,0 +1,14 @@
+# Usage:
+#
+# Other makefiles like Makefile.asciidoc.inc and Makefile.vty-reference.inc add
+# entries to UPLOAD_FILES and CLEAN_FILES.
+#
+# Include this file at the end to have 'upload' and 'clean' targets.
+
+UPLOAD_PATH ?= generic at sysmocom-downloads:documents
+
+upload: $(UPLOAD_FILES)
+	rsync -avz $(UPLOAD_FILES) $(UPLOAD_PATH)/
+
+clean:
+	-rm -rf $(CLEAN_FILES)
diff --git a/build/Makefile.docbook.inc b/build/Makefile.docbook.inc
new file mode 100644
index 0000000..70dfafa
--- /dev/null
+++ b/build/Makefile.docbook.inc
@@ -0,0 +1,35 @@
+# USAGE:
+#
+# - define 'TOPDIR' to point at the git root,
+# - define in 'DOCBOOKS' all root .xml files,
+# - optionally define in 'DOCBOOKS_DEPS' all dependencies common to all .xmls,
+# - include this file,
+# - optionally define further dependencies for individual .pdf targets.
+#
+# e.g.
+#
+#     TOPDIR = ..
+#     DOCBOOKS = osmo_yada.xml osmo_moo.xml
+#     ASCIIDOC_DEPS = for_all/*.xml
+#     include $(TOPDIR)/build/Makefile.docbook.inc
+#     osmo_yada.pdf: yada/*.xml
+#
+# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
+# Makefile from BitBake/OpenEmbedded manuals, edited.
+
+DOCBOOKS_PDF = $(patsubst %.xml,%.pdf,$(DOCBOOKS))
+lint = $(patsubst %.xml,%.lint,$(DOCBOOKS))
+
+CLEAN_FILES += $(DOCBOOKS_PDF) $(lint)
+UPLOAD_FILES += $(DOCBOOKS_PDF)
+
+all: $(DOCBOOKS_PDF)
+
+# Lint the file
+%.xml-lint: %.xml
+	xmllint --xinclude --postvalid --noout $<
+
+# Create a PDF file and lint it before
+%.pdf: %.xml %.xml-lint $(DOCBOOKS_DEPS)
+	dblatex $(dblatex_quiet) -P draft.mode=no $<
+
diff --git a/build/Makefile.inc b/build/Makefile.inc
deleted file mode 100644
index 3905cb0..0000000
--- a/build/Makefile.inc
+++ /dev/null
@@ -1,47 +0,0 @@
-# XSL stylesheets downloaded from http://docbook.sourceforge.net/release/xsl/current/html/
-# Makefile from BitBake/OpenEmbedded manuals
-
-LIBOSMO_DIR ?= ~/source/gsm/libosmocore
-MERGE_DOC := $(LIBOSMO_DIR)/doc/vty/merge_doc.xsl
-UPLOAD_PATH ?= generic at sysmocom-downloads:documents
-
-pdfs = $(patsubst %.xml,%.pdf,$(manuals))
-lint = $(patsubst %.xml,%.xml-lint,$(manuals))
-
-#cleanfiles = $(foreach i,$(types),$(topdir)/$(i))
-cleanfiles += $(pdfs) $(lint)
-
-ifdef DEBUG
-dblatex_quiet =
-define command
-	$(1)
-endef
-else
-dblatex_quiet = -q
-define command
-	@echo $(2) $(3)
-	@$(1)
-endef
-endif
-
-all: $(types)
-
-
-$(types): FORCE
-
-
-pdf: $(pdfs) $(manuals)
-
-
-# Lint the file
-%.xml-lint: %.xml FORCE
-	$(call command,xmllint --xinclude --postvalid --noout $<,XMLLINT,$<)
-
-# Create a PDF file and lint it before
-%.pdf: %.xml %.xml-lint $(EXTRA_DEPS) FORCE
-	$(call command,dblatex $(dblatex_quiet) -P draft.mode=no $<,DBLATEX,$<)
-
-upload: $(pdfs) $(ASCIIDOCPDFS)
-	rsync -avz $(pdfs) $(ASCIIDOCPDFS) $(UPLOAD_PATH)/
-
-FORCE:
diff --git a/build/Makefile.vty-reference.inc b/build/Makefile.vty-reference.inc
new file mode 100644
index 0000000..baf9cf5
--- /dev/null
+++ b/build/Makefile.vty-reference.inc
@@ -0,0 +1,42 @@
+# Usage:
+# Have files:
+# - osmoyada-vty-reference.xml
+#   A docbook root XML including a &chapter-vty; reference.
+# - vty/*additions*.xml
+#   Manual additions to specific VTY nodes, any number of files.
+# - vty/*_reference.xml
+#   Export from VTY 'show online-help', exactly one file.
+#
+# In your Makefile,
+# - define 'TOPDIR' to point at the git root,
+# - define the (single) name of the vty-reference source in VTY_REFERENCE,
+# - include this file.
+#
+# e.g.
+#
+#     TOPDIR = ..
+#     VTY_REFERENCE = osmofoo-vty-reference
+#     include $(TOPDIR)/build/Makefile.vty-reference.inc
+#
+# This uses the Makefile.docbook.inc, you should not mix uses of
+# Makefile.vty-reference.inc and Makefile.docbook.inc.
+
+DOCBOOKS = $(VTY_REFERENCE)
+DOCBOOKS_DEPS = generated/docbook_vty.xml
+include $(TOPDIR)/build/Makefile.docbook.inc
+
+LIBOSMO_DIR ?= ~/source/gsm/libosmocore
+MERGE_DOC = $(LIBOSMO_DIR)/doc/vty/merge_doc.xsl
+
+CLEAN_FILES += generated
+
+generated/docbook_vty.xml: \
+			   vty/*xml \
+			   $(TOPDIR)/common/vty_additions.xml \
+			   $(TOPDIR)/common/chapters/vty.xml \
+			   $(TOPDIR)/vty_reference.xsl
+	$(TOPDIR)/build/vty_reference_combine.sh "$(MERGE_DOC)" \
+		$(TOPDIR)/common/vty_additions.xml \
+		vty/*additions*.xml
+	xsltproc $(TOPDIR)/vty_reference.xsl generated/combined.xml \
+		> generated/docbook_vty.xml
diff --git a/build/vty_reference_combine.sh b/build/vty_reference_combine.sh
new file mode 100755
index 0000000..be234a7
--- /dev/null
+++ b/build/vty_reference_combine.sh
@@ -0,0 +1,25 @@
+#!/bin/sh
+set -e
+
+# the first argument should point at libosmocore/doc/vty/merge_doc.xsl
+MERGE_DOC="$1"
+shift
+
+combined="generated/combined.xml"
+combine_src="generated/combine_src.xml"
+
+reference="vty/*reference.xml"
+test "$(ls -1 $reference | wc -l)" = "1"
+
+set -x
+mkdir -p generated
+cp $reference "$combined"
+
+while [ -n "$1" ]; do
+	addition="$(realpath "$1")"
+	shift
+	mv "$combined" "$combine_src"
+	xsltproc -o "$combined" \
+		--stringparam with "$addition" \
+		"$MERGE_DOC" "$combine_src"
+done

-- 
To view, visit https://gerrit.osmocom.org/3985
To unsubscribe, visit https://gerrit.osmocom.org/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: I9758e04162a480e28c7dc83475b514cf7fd25ec0
Gerrit-PatchSet: 8
Gerrit-Project: osmo-gsm-manuals
Gerrit-Branch: master
Gerrit-Owner: Neels Hofmeyr <nhofmeyr at sysmocom.de>
Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: Neels Hofmeyr <nhofmeyr at sysmocom.de>



More information about the gerrit-log mailing list