v4l2-spec: convert it to use DocBook XML 4.1.2

From: Mauro Carvalho Chehab <mchehab@redhat.com>

DocBook XML 4.1.2 is the docbook dialect spoken at Linux kernel. By
using it, we can now consider adding V4L2 API docs at the kernel tree.

As a bonus, added support for xmlto, with seems to be better supported
nowadays.

Another additional bounus is that two new Makefile targets were added:
	make man - Create V4L2 API man pages
	make man_install - Install V4L2 API man pages

By allowing the addition of V4L2 manpages, it is now easier for
developer to quickly check about a V4L2 API or libv4l2 call syntax and
expected return values.

Priority: normal

Signed-off-by: Mauro Carvalho Chehab <mchehab@redhat.com>

1 files changed, 38 insertions, 10 deletions

diff --git a/v4l2-spec/Makefile b/v4l2-spec/Makefile
index a88420286..ee5d80688 100644
--- a/v4l2-spec/Makefile
+++ b/v4l2-spec/Makefile
@@ -119,8 +119,12 @@ WARN =
 #WARN = -w all -w duplicate -w net
 
 # Stylesheet customization.
+	# docbook/db2 syntax
 CUSTOM_HTML = --dsl custom.dsl\#html
 CUSTOM_PRINT = --dsl custom.dsl\#print
+	# xmlto syntax
+CUSTOM_HTML_XMLTO = -m custom.xsl
+CUSTOM_PRINT_XMLTO = -m custom.xsl
 
 all: capture html-single
 
@@ -130,6 +134,12 @@ html-single: html-single-build.stamp
 
 pdf: pdf-build.stamp
 
+man: man-build.stamp
+
+man_install: man-build.stamp
+	install -d /usr/local/man/man2
+	install -b man/* /usr/local/man/man2
+
 coffeebreak: all html pdf
 
 FUNCS = \
@@ -325,7 +335,8 @@ DOCUMENTED = \
 	-e "s/\(enum *\)v4l2_mpeg_cx2341x_video_\([a-z]*_spatial_filter_type\)/\1<link linkend=\"\2\">v4l2_mpeg_cx2341x_video_\2<\/link>/g" \
 	-e "s/\(\(enum\|struct\) *\)\(v4l2_[a-zA-Z0-9_]*\)/\1<link linkend=\"\3\">\3<\/link>/g" \
 	-e "s/\(V4L2_PIX_FMT_[A-Z0-9_]\+\) /<link linkend=\"\1\">\1<\/link> /g" \
-	-e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta"
+	-e ":a;s/\(linkend=\".*\)_\(.*\">\)/\1-\2/;ta" \
+	-e "s/(linkend=\")v4l2-mpeg-vbi-ITV0/\1)v4l2_mpeg_vbi_itv0-1/g"
 
 libv4l-fmt.sgml:
 	cat ../v4l2-apps/libv4l/libv4lconvert/*.c| \
@@ -460,10 +471,14 @@ indices.sgml: Makefile
 # HTML version.
 html-build.stamp: Makefile checks $(SGMLS) $(GIFPICS)
 	rm -rf v4l2
-	if which docbook2html >/dev/null ; then \
-	  docbook2html $(WARN) $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \
+	if which xmlto >/dev/null ; then \
+	  xmlto xhtml $(WARN) $(CUSTOM_HTML_XMLTO) -o v4l2 v4l2.sgml ; \
+	elif which docbook2html >/dev/null ; then \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  docbook2html $(WARN) $$DCL $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \
 	else \
-	  db2html $(WARN) $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  db2html $(WARN) $$DCL $(CUSTOM_HTML) --output v4l2 v4l2.sgml ; \
 	fi
 	cp $(GIFPICS) v4l2/
 	cd v4l2 ; \
@@ -477,11 +492,15 @@ html-build.stamp: Makefile checks $(SGMLS) $(GIFPICS)
 # is more convenient than clicking through dozens of pages.
 html-single-build.stamp: Makefile checks $(SGMLS) $(GIFPICS)
 	rm -rf v4l2-single
-	if which docbook2html >/dev/null; then \
-	  docbook2html $(WARN) $(CUSTOM_HTML) --nochunks \
+	if which xmlto >/dev/null ; then \
+	  xmlto html-nochunks $(WARN) $(CUSTOM_HTML_XMLTO) -o v4l2-single v4l2.sgml ; \
+	elif which docbook2html >/dev/null ; then \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  docbook2html $$DCL $(WARN) $(CUSTOM_HTML) --nochunks \
 	    --output v4l2-single v4l2.sgml ; \
 	else \
-	  db2html $(WARN) $(CUSTOM_HTML) --nochunks \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  db2html $$DCL $(WARN) $(CUSTOM_HTML) --nochunks \
 	    --output v4l2-single v4l2.sgml ; \
 	fi
 	cp $(GIFPICS) v4l2-single/
@@ -490,13 +509,22 @@ html-single-build.stamp: Makefile checks $(SGMLS) $(GIFPICS)
 
 # For printing.
 pdf-build.stamp: Makefile checks $(SGMLS) $(PDFPICS)
-	if which docbook2pdf >/dev/null; then \
-	  docbook2pdf $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \
+	if which db2pdf >/dev/null ; then \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl|head -1`"; \
+	  db2pdf $$DCL $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \
+	elif which xmlto >/dev/null ; then \
+	  xmlto pdf $(WARN) $(CUSTOM_HTML_XMLTO) -o v4l2-single v4l2.sgml ; \
 	else \
-	  db2pdf $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  docbook2pdf $$DCL $(WARN) $(CUSTOM_PRINT) v4l2.sgml ; \
 	fi
 	touch pdf-build.stamp
 
+
+# For man
+man-build.stamp: Makefile checks $(SGMLS) $(PDFPICS)
+	xmlto man $(WARN) $(CUSTOM_HTML_XMLTO) -o man v4l2.sgml
+
 # Example.
 capture: ../v4l2-apps/test/capture-example.c
 	gcc $^ -o $@