From 10ce3d399e9200a9e9427058dab8724d03afa4a3 Mon Sep 17 00:00:00 2001
From: Florin Iucha <florin@signbit.net>
Date: Mon, 27 Apr 2020 11:38:30 -0400
Subject: [PATCH] [Tools] Add an example documentation generation flow

---
 doc/getting_started.md       | 41 ++++++++++++++++++++++++++++++++++++
 src/dist/bin/list_figures.sh |  3 +++
 src/dist/examples/Makefile   | 34 ++++++++++++++++++++++++++++++
 3 files changed, 78 insertions(+)
 create mode 100755 src/dist/bin/list_figures.sh
 create mode 100644 src/dist/examples/Makefile

diff --git a/doc/getting_started.md b/doc/getting_started.md
index 0256b5e..f127e9b 100644
--- a/doc/getting_started.md
+++ b/doc/getting_started.md
@@ -131,3 +131,44 @@ and it does not support all SAMx functionality.
 
 `generate_header` is part of the support for literate programing in SAMx, where we define enumerations and data
 structures inside SAMx, then generate both end-user documentation and source code from the same model.
+
+Makefile
+--------
+
+There is an experimental Makefile which implements a full documentation flow, tested on Ubuntu 18.04. The following packages
+are required: xsltproc, fop, docbook-xsl-ns .
+
+Here is an example session, assuming we have a document with included images which can all be processed by the included PlantUML processor:
+
+```shell script
+$ ls
+samx_language.samx
+$ make -f ~/tools/samxj-0.4.7/examples/Makefile samx_language.pdf
+~/tools/samxj-0.4.7/bin/to_xml -b -i samx_language.samx -o samx_language.dbk -s ~/tools/samxj-0.4.7/schemas/docbook.rng.gz
+Enable DocBook mode
+XML output is well-formed
+DocBook document validated using Jing
+xsltproc -o samx_language.fo /usr/share/xml/docbook/stylesheet/docbook-xsl-ns/fo/docbook.xsl samx_language.dbk
+Making portrait pages on USletter paper (8.5inx11in)
+~/tools/samxj-0.4.7/bin/extract_code -i samx_language.samx -o .
+Writing /tmp/test/ditaa-example.plantuml
+java -jar ~/tools/samxj-0.4.7/lib/plantuml-1.2020.8.jar ditaa-example.plantuml
+fop -pdf samx_language.pdf -fo samx_language.fo
+[warning] /usr/bin/fop: JVM flavor 'sun' not understood
+[WARN] FOUserAgent - Font "Symbol,normal,700" not found. Substituting with "Symbol,normal,400".
+[WARN] FOUserAgent - Font "ZapfDingbats,normal,700" not found. Substituting with "ZapfDingbats,normal,400".
+[INFO] FOUserAgent - Rendered page #1.
+[INFO] FOUserAgent - Rendered page #2.
+[INFO] FOUserAgent - Rendered page #3.
+[INFO] FOUserAgent - Rendered page #4.
+[INFO] FOUserAgent - Rendered page #5.
+[INFO] FOUserAgent - Rendered page #6.
+[INFO] FOUserAgent - Rendered page #7.
+[INFO] FOUserAgent - Rendered page #8.
+[INFO] FOUserAgent - Rendered page #9.
+[INFO] FOUserAgent - Rendered page #10.
+rm ditaa-example.plantuml samx_language.fo ditaa-example.png samx_language.dbk
+```
+
+This script is meant as an example and might be changed or moved in a subsequent release. The script outputs the exact
+commands used so it can be used as a starting point for your own custom workflow.
diff --git a/src/dist/bin/list_figures.sh b/src/dist/bin/list_figures.sh
new file mode 100755
index 0000000..a80bde0
--- /dev/null
+++ b/src/dist/bin/list_figures.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+
+sed -n '/^ *```/s/ *```(\(\w*\)).*(\#\([-a-z.0-9]*\))/\2.\1/p;' $1
diff --git a/src/dist/examples/Makefile b/src/dist/examples/Makefile
new file mode 100644
index 0000000..058acf9
--- /dev/null
+++ b/src/dist/examples/Makefile
@@ -0,0 +1,34 @@
+# Example documentation flow
+#
+# (Tested on Ubuntu 18.04)
+#
+# Prerequisites:
+# 	sudo apt install xsltproc fop docbook-xsl-ns
+
+TOOLS_PATH=$(abspath $(dir $(realpath $(firstword $(MAKEFILE_LIST))))..)
+STYLESHEETS=/usr/share/xml/docbook/stylesheet/docbook-xsl-ns
+
+SOURCE_FILE=$(MAKECMDGOALS:.pdf=.samx)
+DEPENDENCIES=$(shell $(TOOLS_PATH)/bin/list_figures.sh $(SOURCE_FILE))
+
+%.dbk: %.samx
+	$(TOOLS_PATH)/bin/to_xml -b -i $^ -o $@ -s $(TOOLS_PATH)/schemas/docbook.rng.gz
+
+$(DEPENDENCIES): $(SOURCE_FILE)
+	$(TOOLS_PATH)/bin/extract_code -i $(SOURCE_FILE) -o .
+
+.INTERMEDIATE: $(DEPENDENCIES)
+
+%.png: %.plantuml
+	java -jar $(TOOLS_PATH)/lib/plantuml-1.2020.8.jar $^
+
+%.fo: %.dbk 
+	xsltproc -o $@ $(STYLESHEETS)/fo/docbook.xsl $<
+
+%.pdf: %.fo $(DEPENDENCIES:.plantuml=.png)
+	fop -pdf $@ -fo $<
+
+clean:
+	$(RM) *.fo *.img *.pdf *.plantuml
+
+.PHONY: clean