[Spice-devel] [RFC PATCH 1/2] Start adding protocol file documentation

[Frediano Ziglio]

The protocol file is not documented and people have to read code to
understand the specification.
This can lead to unexpected or not optimal results so it's better
to have it documented.
The m4/spice_manual.m4 came from spice server and is meant to be
reused.

Signed-off-by: Frediano Ziglio <fziglio at redhat.com>
---
 Makefile.am             |  2 +-
 configure.ac            |  2 ++
 docs/Makefile.am        | 17 +++++++++++++++++
 docs/spice_protocol.txt |  2 ++
 m4/spice_manual.m4      | 32 ++++++++++++++++++++++++++++++++
 5 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 docs/Makefile.am
 create mode 100644 docs/spice_protocol.txt
 create mode 100644 m4/spice_manual.m4

diff --git a/Makefile.am b/Makefile.am
index 63d7956..ee0a1e2 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,7 +1,7 @@
 NULL =
 ACLOCAL_AMFLAGS = -I m4
 
-SUBDIRS = python_modules common tests
+SUBDIRS = python_modules common tests docs
 
 EXTRA_DIST =				\
 	spice_codegen.py		\
diff --git a/configure.ac b/configure.ac
index c3ad5a4..6d9f378 100644
--- a/configure.ac
+++ b/configure.ac
@@ -17,6 +17,7 @@ AM_INIT_AUTOMAKE([1.11 dist-xz no-dist-gzip tar-ustar foreign -Wall -Werror])
 AM_MAINTAINER_MODE
 AM_SILENT_RULES([yes])
 LT_INIT
+SPICE_MANUAL
 
 AC_PROG_CC
 AC_PROG_CC_C99
@@ -50,6 +51,7 @@ AC_CONFIG_FILES([
   common/Makefile
   python_modules/Makefile
   tests/Makefile
+  docs/Makefile
 ])
 
 AH_BOTTOM([
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..47f40c3
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,17 @@
+NULL =
+ASCIIDOC_FLAGS = -a icons -a toc
+
+EXTRA_DIST =					\
+	spice_protocol.html			\
+	spice_protocol.txt				\
+	$(NULL)
+
+if BUILD_HTML_MANUAL
+all-local: spice_protocol.html
+
+spice_protocol.html: spice_protocol.txt
+	$(AM_V_GEN) $(ASCIIDOC) -n $(ASCIIDOC_FLAGS) -o $@ $<
+endif
+
+clean-local:
+	rm -f spice_protocol.html
diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
new file mode 100644
index 0000000..b62da25
--- /dev/null
+++ b/docs/spice_protocol.txt
@@ -0,0 +1,2 @@
+Spice protocol format file
+==========================
diff --git a/m4/spice_manual.m4 b/m4/spice_manual.m4
new file mode 100644
index 0000000..c36f6f7
--- /dev/null
+++ b/m4/spice_manual.m4
@@ -0,0 +1,32 @@
+dnl SPICE_MANUAL
+dnl ------------
+dnl Check if user wants manuals to be compiled and
+dnl if all programs (asciidoc and a2x) are available
+dnl ------------
+dnl Shell defines:
+dnl - have_asciidoc yes or not is asciidoc program is available
+dnl Automake macros:
+dnl - A2X a2x program or empty
+dnl - ASCIIDOC asciidoc program or emtpy
+dnl - BUILD_MANUAL if asciidoc and a2x are available
+dnl - BUILD_HTML_MANUAL if asciidoc is available (html can be produced)
+dnl - BUILD_CHUNKED_MANUAL if a2x is available
+AC_DEFUN([SPICE_MANUAL],[
+    AC_ARG_ENABLE([manual],
+                   AS_HELP_STRING([--enable-manual=@<:@auto/yes/no@:>@],
+                                  [Build SPICE manual]),
+                   [],
+                   [enable_manual="auto"])
+    if test "x$enable_manual" != "xno"; then
+        AC_PATH_PROG([ASCIIDOC], [asciidoc])
+        AS_IF([test -z "$ASCIIDOC" && test "x$enable_manual" = "xyes"],
+              [AC_MSG_ERROR([asciidoc is missing and build of manual was requested])])
+        AC_PATH_PROG([A2X], [a2x])
+        AS_IF([test -z "$A2X" && test "x$enable_manual" = "xyes"],
+              [AC_MSG_ERROR([a2x is missing and build of manual was requested])])
+    fi
+    AS_IF([test -n "$ASCIIDOC"], [have_asciidoc=yes], [have_asciidoc=no])
+    AM_CONDITIONAL([BUILD_MANUAL], [test -n "$ASCIIDOC" || test -n "$A2X"])
+    AM_CONDITIONAL([BUILD_HTML_MANUAL], [test -n "$ASCIIDOC"])
+    AM_CONDITIONAL([BUILD_CHUNKED_MANUAL], [test -n "$A2X"])
+])
-- 
2.7.4