Makefile.*.inc: adjust to out-of-tree building

Makefile.asciidoc.inc: create a symlink for the root adoc file, from
which a PDF gets generated, from the srcdir to the builddir. This file
may include other adoc files, which do not get symlinked. We need to do
this, because a2x (the program generating the PDF file) does not have a
parameter for the output file, and will otherwise generate the PDF in
the srcdir instead of the builddir. Do the same in the check target, so
the relative include paths work the same.

Makefile.asciidoc.inc, Makefile.docbook.inc: set the include paths for
the xstl parser, as well as the LaTeX compiler, so they can find the
files they need from both OSMO_GSM_MANUALS_DIR and builddir.

Makefile.asciidoc.inc, Makefile.docbook.inc: refer to the output file
$@ with $(notdir $@). This removes the path from the file, like
basename from coreutils. The output file will then be placed in the
builddir instead of the srcdir.

Makefile.vty-reference.inc: use $(srcdir) in references to vty/*.xml
files.

(moving manuals to project repositories 12/19)

Related: OS#3385
Change-Id: Ie6b212a6518f0fc29fae610a37ae6c533189278d

build/Makefile.asciidoc.inc

@@ -56,12 +56,24 @@ $(ASCIIDOC_PDF): %.pdf: %.adoc %-docinfo.xml \
 		$(OSMO_GSM_MANUALS_DIR)/common/*/*.adoc \
 		$(OSMO_GSM_MANUALS_DIR)/common/images/* \
 		build common
+
+	# a2x can't use a different output file. To support out-of-tree builds,
+	# we create a symlink at $(builddir)/srcfile.adoc pointing at
+	# $(srcdir)/srcfile.adoc. $< is the $(srcdir)/srcfile.adoc,
+	# $(notdir) is like basename from coreutils, and $(builddir) is $PWD.
+	if ! [ -f $(notdir $<) ]; then \
+		ln -s $< $(notdir $<); \
+	fi
+
+	# TEXINPUTS: find LaTeX includes like \includegraphics{./common/images/sysmocom.pdf}
+	# in $(OSMO_GSM_MANUALS_DIR).
 	@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" \
 	  || true
-	a2x $(A2X_OPTS) $< || (echo "ERROR: a2x failed! Running asciidoc to get verbose errors..."; \
-		asciidoc -v $(ASCIIDOC_OPTS) $<; exit 1)
+	TEXINPUTS="$(OSMO_GSM_MANUALS_DIR)" \
+		a2x $(A2X_OPTS) $(notdir $<) || (echo "ERROR: a2x failed! Running asciidoc to get verbose errors..."; \
+			asciidoc -v $(ASCIIDOC_OPTS) $(notdir $<); exit 1)
 
 check: $(ASCIIDOC_CHECKS)
 
@@ -70,9 +82,18 @@ $(ASCIIDOC_CHECKS): %.check: %.adoc %-docinfo.xml \
 		$(OSMO_GSM_MANUALS_DIR)/common/chapters/*.adoc \
 		$(ASCIIDOC_DEPS) \
 		build common
-	asciidoc -v $(ASCIIDOC_OPTS) $< > $@ 2>&1
+
+	# out-of-tree building: use a symlink to the output file like done in
+	# the non-check build above, so the relative include paths work the
+	# same.
+	if ! [ -f $(notdir $<) ]; then \
+		ln -s $< $(notdir $<); \
+	fi
+
+	asciidoc -v $(ASCIIDOC_OPTS) $(notdir $<) > $(notdir $@) 2>&1
+
 	# Make absolutely sure that the %.check target is updated.
-	touch $@
+	touch $(notdir $@)
 	# Do print the WARNING output but return error if any was found
 	# (grep -v would omit the WARNING output from the log).
-	@grep WARNING $@ && exit 1 || exit 0
+	@grep WARNING $(notdir $@) && exit 1 || exit 0

build/Makefile.docbook.inc

@@ -32,6 +32,8 @@ all: $(DOCBOOKS_PDF)
 	xmllint --xinclude --postvalid --noout $<
 
 # Create a PDF file and lint it before
+# xslt path: find includes in both $(OSMO_GSM_MANUALS_DIR)/common/chapters and $(builddir)/generated
 %.pdf: %.xml %.xml-lint $(DOCBOOKS_DEPS) build common
-	dblatex $(dblatex_quiet) -P draft.mode=no $<
+	dblatex --xslt-opts="--path $(realpath $(OSMO_GSM_MANUALS_DIR))/common/chapters:$$PWD/generated" \
+		$(dblatex_quiet) -P draft.mode=no -o $(notdir $@) $<
 

build/Makefile.vty-reference.inc

@@ -32,13 +32,13 @@ MERGE_DOC = $(shell realpath $(OSMO_GSM_MANUALS_DIR)/merge_doc.xsl)
 CLEAN_FILES += generated
 
 generated/docbook_vty.xml: \
-			   vty/*xml \
+			   $(srcdir)/vty/*xml \
 			   $(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \
 			   $(OSMO_GSM_MANUALS_DIR)/common/chapters/vty.xml \
 			   $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl
 	$(OSMO_GSM_MANUALS_DIR)/build/vty_reference_combine.sh "$(MERGE_DOC)" \
 		$(srcdir)/vty/*reference.xml \
 		$(OSMO_GSM_MANUALS_DIR)/common/vty_additions.xml \
-		vty/*additions*.xml
+		$(srcdir)/vty/*additions*.xml
 	xsltproc $(OSMO_GSM_MANUALS_DIR)/vty_reference.xsl generated/combined.xml \
 		> generated/docbook_vty.xml