dvb-spec: Compile from Documentation/DocBook

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

Priority: normal

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

6 files changed, 566 insertions, 0 deletions

diff --git a/dvb-spec/dvbapi/Makefile b/dvb-spec/dvbapi/Makefile
new file mode 100644
index 000000000..9a1363da1
--- /dev/null
+++ b/dvb-spec/dvbapi/Makefile
@@ -0,0 +1,152 @@
+SHELL=/bin/bash
+
+SGMLS = \
+	dvbapi.sgml \
+	intro.xml \
+	frontend.xml \
+	demux.xml \
+	video.xml \
+	audio.xml \
+	ca.xml \
+	net.xml \
+	kdapi.xml \
+	examples.xml \
+	fdl-appendix.xml \
+	entities.xml \
+
+PDFPICS = \
+	dvbstb.pdf \
+
+GIFPICS = \
+	dvbstb.png \
+
+# Some Jade warnings for authors.
+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: html-single
+
+html: html-build.stamp
+
+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
+
+.PHONY: links
+
+$(SGMLS): links
+$(PDFPICS): links
+$(GIFPICS): links
+
+links::
+	ln -sf ../../linux/Documentation/DocBook/dvb/* .
+	ln -sf ../../linux/Documentation/DocBook/v4l/fdl-appendix.xml .
+
+entities.xml: Makefile $(SGMLS)
+	echo "<!-- Generated file! Do not edit. -->" >$@
+	echo -e "\n<!-- Subsections -->" >>$@
+	for file in $(SGMLS) ; do \
+	  entity=`echo "$$file" | sed 's/.xml//;s/\./-/g'` ; \
+	  if ! echo "$$file" | \
+	    grep -q -E -e '^(func|vidioc|pixfmt)-' ; then \
+	      echo "<!ENTITY sub-$$entity SYSTEM \"$$file\">" >>$@ ; \
+	 fi ; \
+	done
+
+# Jade can auto-generate a list-of-tables, which includes all structs,
+# but we only want data types, all types, and sorted please.
+indices.xml: Makefile $(SGMLS)
+	echo "<!-- Generated file! Do not edit. -->" >$@
+	echo -e "\n<index><title>List of Types</title>" >>$@
+	for ident in $(TYPES) ; do \
+	  id=`echo $$ident | tr _ -` ; \
+	  echo "<indexentry><primaryie><link" \
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done
+	for ident in $(ENUMS) ; do \
+	  echo "<indexentry><primaryie>enum&nbsp;<link" \
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done
+	for ident in $(STRUCTS) ; do \
+	  id=`echo $$ident | tr _ -` ; \
+	  echo "<indexentry><primaryie>struct&nbsp;<link" \
+	    "linkend='$$id'>$$ident</link></primaryie></indexentry>" >>$@ ; \
+	done
+	echo "</index>" >>$@
+
+# HTML version.
+html-build.stamp: Makefile $(SGMLS) $(GIFPICS)
+	rm -rf dvbapi
+	if which xmlto >/dev/null ; then \
+	  xmlto xhtml $(WARN) $(CUSTOM_HTML_XMLTO) -o dvbapi dvbapi.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 dvbapi dvbapi.sgml ; \
+	else \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  db2html $(WARN) $$DCL $(CUSTOM_HTML) --output dvbapi dvbapi.sgml ; \
+	fi
+	cp $(GIFPICS) dvbapi/
+	cd dvbapi ; \
+	test -e index.html || ln -s book1.htm index.html ; \
+	test -e capture-example.html || \
+	  ln -s `grep -l getopt_long *.htm` capture-example.html
+	chmod a+rX -R dvbapi
+	touch html-build.stamp
+
+# For online version. When you have a dial-up connection a single file
+# is more convenient than clicking through dozens of pages.
+html-single-build.stamp: Makefile $(SGMLS) $(GIFPICS)
+	rm -rf dvbapi-single
+	if which xmlto >/dev/null ; then \
+	  xmlto html-nochunks $(WARN) $(CUSTOM_HTML_XMLTO) -o dvbapi-single dvbapi.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 dvbapi-single dvbapi.sgml ; \
+	else \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  db2html $$DCL $(WARN) $(CUSTOM_HTML) --nochunks \
+	    --output dvbapi-single dvbapi.sgml ; \
+	fi
+	cp $(GIFPICS) dvbapi-single/
+	chmod a+rX -R dvbapi-single
+	touch html-single-build.stamp
+
+# For printing.
+pdf-build.stamp: Makefile $(SGMLS) $(PDFPICS)
+	if which db2pdf >/dev/null ; then \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl|head -1`"; \
+	  db2pdf $$DCL $(WARN) $(CUSTOM_PRINT) dvbapi.sgml ; \
+	elif which xmlto >/dev/null ; then \
+	  xmlto pdf $(WARN) $(CUSTOM_HTML_XMLTO) -o dvbapi-single dvbapi.sgml ; \
+	else \
+	  export DCL="--dcl `find /usr/share/sgml -name xml.dcl |head -1`"; \
+	  docbook2pdf $$DCL $(WARN) $(CUSTOM_PRINT) dvbapi.sgml ; \
+	fi
+	touch pdf-build.stamp
+
+
+# For man
+man-build.stamp: Makefile $(SGMLS) $(PDFPICS)
+	xmlto man $(WARN) $(CUSTOM_HTML_XMLTO) -o man dvbapi.sgml
+
+distclean clean:
+	rm -f *.stamp
+	rm -f indices.xml entities.xml
+	find . -type l -exec rm '{}' \;
+
diff --git a/dvb-spec/dvbapi/README b/dvb-spec/dvbapi/README
new file mode 100644
index 000000000..7d908c8c8
--- /dev/null
+++ b/dvb-spec/dvbapi/README
@@ -0,0 +1,11 @@
+This directory doesn't contain the official DVB API.
+
+It contains a port from LaTex to Docbook XML 4.1.2
+
+It is still a work undergoing. Contributions are welcome.
+
+CURRENT STATUS:
+
+All chapters were converted. The resulting pdf and html are close to the
+original LaTex book. Yet, it lacks some efforts to improve
+the output layout and it lacks a topic index.
diff --git a/dvb-spec/dvbapi/ca.sgml b/dvb-spec/dvbapi/ca.sgml
new file mode 100644
index 000000000..b1f1d2fad
--- /dev/null
+++ b/dvb-spec/dvbapi/ca.sgml
@@ -0,0 +1,221 @@
+<title>DVB CA Device</title>
+<para>The DVB CA device controls the conditional access hardware. It can be accessed through
+<emphasis role="tt">/dev/dvb/adapter0/ca0</emphasis>. Data types and and ioctl definitions can be accessed by
+including <emphasis role="tt">linux/dvb/ca.h</emphasis> in your application.
+</para>
+
+<section id="ca_data_types">
+<title>CA Data Types</title>
+
+
+<section id="ca_slot_info_t">
+<title>ca_slot_info_t</title>
+ <programlisting>
+ /&#x22C6; slot interface types and info &#x22C6;/
+
+ typedef struct ca_slot_info_s {
+	 int num;               /&#x22C6; slot number &#x22C6;/
+
+	 int type;           /&#x22C6; CA interface this slot supports &#x22C6;/
+ #define CA_CI            1  /&#x22C6; CI high level interface &#x22C6;/
+ #define CA_CI_LINK       2  /&#x22C6; CI link layer level interface &#x22C6;/
+ #define CA_CI_PHYS       4  /&#x22C6; CI physical layer level interface &#x22C6;/
+ #define CA_SC          128  /&#x22C6; simple smart card interface &#x22C6;/
+
+	 unsigned int flags;
+ #define CA_CI_MODULE_PRESENT 1 /&#x22C6; module (or card) inserted &#x22C6;/
+ #define CA_CI_MODULE_READY   2
+ } ca_slot_info_t;
+</programlisting>
+
+</section>
+<section id="ca_descr_info_t">
+<title>ca_descr_info_t</title>
+ <programlisting>
+ typedef struct ca_descr_info_s {
+	 unsigned int num;  /&#x22C6; number of available descramblers (keys) &#x22C6;/
+	 unsigned int type; /&#x22C6; type of supported scrambling system &#x22C6;/
+ #define CA_ECD           1
+ #define CA_NDS           2
+ #define CA_DSS           4
+ } ca_descr_info_t;
+</programlisting>
+
+</section>
+<section id="ca_cap_t">
+<title>ca_cap_t</title>
+ <programlisting>
+ typedef struct ca_cap_s {
+	 unsigned int slot_num;  /&#x22C6; total number of CA card and module slots &#x22C6;/
+	 unsigned int slot_type; /&#x22C6; OR of all supported types &#x22C6;/
+	 unsigned int descr_num; /&#x22C6; total number of descrambler slots (keys) &#x22C6;/
+	 unsigned int descr_type;/&#x22C6; OR of all supported types &#x22C6;/
+ } ca_cap_t;
+</programlisting>
+
+</section>
+<section id="ca_msg_t">
+<title>ca_msg_t</title>
+ <programlisting>
+ /&#x22C6; a message to/from a CI-CAM &#x22C6;/
+ typedef struct ca_msg_s {
+	 unsigned int index;
+	 unsigned int type;
+	 unsigned int length;
+	 unsigned char msg[256];
+ } ca_msg_t;
+</programlisting>
+
+</section>
+<section id="ca_descr_t">
+<title>ca_descr_t</title>
+ <programlisting>
+ typedef struct ca_descr_s {
+	 unsigned int index;
+	 unsigned int parity;
+	 unsigned char cw[8];
+ } ca_descr_t;
+</programlisting>
+ </section></section>
+<section id="ca_function_calls">
+<title>CA Function Calls</title>
+
+
+<section id="ca_fopen">
+<title>open()</title>
+<para>DESCRIPTION
+</para>
+<informaltable><tgroup cols="1"><tbody><row><entry
+ align="char">
+<para>This system call opens a named ca device (e.g. /dev/ost/ca) for subsequent use.</para>
+<para>When an open() call has succeeded, the device will be ready for use.
+ The significance of blocking or non-blocking mode is described in the
+ documentation for functions where there is a difference. It does not affect the
+ semantics of the open() call itself. A device opened in blocking mode can later
+ be put into non-blocking mode (and vice versa) using the F_SETFL command
+ of the fcntl system call. This is a standard system call, documented in the Linux
+ manual page for fcntl. Only one user can open the CA Device in O_RDWR
+ mode. All other attempts to open the device in this mode will fail, and an error
+ code will be returned.</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+<para>SYNOPSIS
+</para>
+<informaltable><tgroup cols="1"><tbody><row><entry
+ align="char">
+<para>int open(const char &#x22C6;deviceName, int flags);</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+<para>PARAMETERS
+</para>
+<informaltable><tgroup cols="2"><tbody><row><entry
+ align="char">
+<para>const char
+ *deviceName</para>
+</entry><entry
+ align="char">
+<para>Name of specific video device.</para>
+</entry>
+ </row><row><entry
+ align="char">
+<para>int flags</para>
+</entry><entry
+ align="char">
+<para>A bit-wise OR of the following flags:</para>
+</entry>
+ </row><row><entry
+ align="char">
+</entry><entry
+ align="char">
+<para>O_RDONLY read-only access</para>
+</entry>
+ </row><row><entry
+ align="char">
+</entry><entry
+ align="char">
+<para>O_RDWR read/write access</para>
+</entry>
+ </row><row><entry
+ align="char">
+</entry><entry
+ align="char">
+<para>O_NONBLOCK open in non-blocking mode</para>
+</entry>
+ </row><row><entry
+ align="char">
+</entry><entry
+ align="char">
+<para>(blocking mode is the default)</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+<para>ERRORS
+</para>
+<informaltable><tgroup cols="2"><tbody><row><entry
+ align="char">
+<para>ENODEV</para>
+</entry><entry
+ align="char">
+<para>Device driver not loaded/available.</para>
+</entry>
+ </row><row><entry
+ align="char">
+<para>EINTERNAL</para>
+</entry><entry
+ align="char">
+<para>Internal error.</para>
+</entry>
+ </row><row><entry
+ align="char">
+<para>EBUSY</para>
+</entry><entry
+ align="char">
+<para>Device or resource busy.</para>
+</entry>
+ </row><row><entry
+ align="char">
+<para>EINVAL</para>
+</entry><entry
+ align="char">
+<para>Invalid argument.</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+
+</section>
+<section id="ca_fclose">
+<title>close()</title>
+<para>DESCRIPTION
+</para>
+<informaltable><tgroup cols="1"><tbody><row><entry
+ align="char">
+<para>This system call closes a previously opened audio device.</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+<para>SYNOPSIS
+</para>
+<informaltable><tgroup cols="1"><tbody><row><entry
+ align="char">
+<para>int close(int fd);</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+<para>PARAMETERS
+</para>
+<informaltable><tgroup cols="2"><tbody><row><entry
+ align="char">
+<para>int fd</para>
+</entry><entry
+ align="char">
+<para>File descriptor returned by a previous call to open().</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+<para>ERRORS
+</para>
+<informaltable><tgroup cols="2"><tbody><row><entry
+ align="char">
+<para>EBADF</para>
+</entry><entry
+ align="char">
+<para>fd is not a valid open file descriptor.</para>
+</entry>
+ </row></tbody></tgroup></informaltable>
+ </section>
+</section>
diff --git a/dvb-spec/dvbapi/custom.dsl b/dvb-spec/dvbapi/custom.dsl
new file mode 100644
index 000000000..12a5e91d4
--- /dev/null
+++ b/dvb-spec/dvbapi/custom.dsl
@@ -0,0 +1,52 @@
+<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
+<!ENTITY % html "IGNORE">
+<![%html;[
+<!ENTITY % print "IGNORE">
+<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA dsssl>
+]]>
+<!ENTITY % print "INCLUDE">
+<![%print;[
+<!ENTITY docbook.dsl PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA dsssl>
+]]>
+]>
+
+<style-sheet>
+
+<style-specification id="print" use="docbook">
+<style-specification-body>
+
+<!-- See docbook-dsssl-1.x/doc -->
+(define %generate-reference-toc% #t)
+(define %refentry-new-page% #t)
+(define %number-programlisting-lines% #f)
+(define %section-autolabel% #t)
+(define bop-footnotes #t)
+<!-- (define %show-comments% #f) -->
+(define ($generate-book-lot-list$)
+  (list (normalize "figure")
+    (normalize "example")))
+<!-- A4 | USletter -->
+(define %paper-type% "A4")
+
+</style-specification-body>
+</style-specification>
+
+<style-specification id="html" use="docbook">
+<style-specification-body>
+
+<!-- See docbook-dsssl-1.x/doc -->
+(define %generate-reference-toc% #t)
+(define %number-programlisting-lines% #f)
+(define %section-autolabel% #t)
+(define bop-footnotes #t)
+<!-- (define %show-comments% #f) -->
+(define ($generate-book-lot-list$)
+  (list (normalize "figure")
+    (normalize "example")))
+
+</style-specification-body>
+</style-specification>
+
+<external-specification id="docbook" document="docbook.dsl">
+
+</style-sheet>
diff --git a/dvb-spec/dvbapi/custom.xsl b/dvb-spec/dvbapi/custom.xsl
new file mode 100644
index 000000000..e1556c37c
--- /dev/null
+++ b/dvb-spec/dvbapi/custom.xsl
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<!-- Extension for HTML files -->
+<param name="html.ext" select="'.html'"/>
+
+<!-- Generate TOCs for book, article, part -->
+<param name="generate.book.toc">1</param>
+<param name="generate.article.toc">0</param>
+<param name="generate.part.toc">0</param>
+<param name="toc.chapter.depth">0</param>
+
+<param name="refentry.separator">1</param>
+
+<param name="chunk.first.sections">1</param>
+<param name="chunk.id.as.filename">1</param>
+<param name="chunk.separate.lots">1</param>
+
+<param name="funcsynopsis.style">ansi</param>
+<param name="funcsynopsis.tabular.threshold">80</param>
+<param name="funcsynopsis.decoration">1</param>
+
+<param name="chapter.autolabel">1</param>
+<param name="section.autolabel">1</param>
+<param name="section.label.includes.component.label">1</param>
+<param name="toc.section.depth">3</param>
+
+<param name="paper.type">A4</param>
+</stylesheet>
diff --git a/dvb-spec/dvbapi/dvbapi.sgml b/dvb-spec/dvbapi/dvbapi.sgml
new file mode 100644
index 000000000..377fe8fba
--- /dev/null
+++ b/dvb-spec/dvbapi/dvbapi.sgml
@@ -0,0 +1,101 @@
+<?xml version='1.0' encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY % entities SYSTEM "./entities.xml"> %entities;
+<!ENTITY i2c "I<superscript>2</superscript>C">
+]>
+
+<book id="dvbapi">
+<bookinfo>
+<title>LINUX DVB API</title>
+<subtitle>Version 3</subtitle>
+
+<authorgroup><author>
+<firstname>Ralph</firstname>
+<surname>Metzler</surname>
+<othername role="mi">J. K.</othername>
+<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
+</author>
+<author>
+<firstname>Marcus</firstname>
+<surname>Metzler</surname>
+<othername role="mi">O. C.</othername>
+<affiliation><address><email>rjkm@metzlerbros.de</email></address></affiliation>
+</author>
+<author>
+<firstname>Mauro</firstname>
+<surname>Chehab</surname>
+<othername role="mi">Carvalho</othername>
+<affiliation><address><email>mchehab@infradead.org</email></address></affiliation>
+<contrib>Ported document to Docbook XML.</contrib>
+</author>
+</authorgroup>
+
+<copyright>
+<year>2002</year>
+<year>2003</year>
+<year>2009</year>
+<holder>Convergence GmbH</holder>
+</copyright>
+
+<legalnotice>
+<para>Permission is granted to copy, distribute and/or modify
+this document under the terms of the GNU Free Documentation License,
+Version 1.1 or any later version published by the Free Software
+Foundation. A copy of the license is included in the chapter entitled
+"GNU Free Documentation License"</para>
+</legalnotice>
+
+<revhistory>
+<!-- Put document revisions here, newest first. -->
+<revision>
+<revnumber>2.0.0</revnumber>
+<date>2009-09-06</date>
+<authorinitials>mcc</authorinitials>
+<revremark>Conversion from LaTex to DocBook XML. The
+contents is the same as the original LaTex version.</revremark>
+</revision>
+<revision>
+<revnumber>1.0.0</revnumber>
+<date>2003-07-24</date>
+<authorinitials>rjkm</authorinitials>
+<revremark>Initial revision on LaTEX.</revremark>
+</revision>
+</revhistory>
+
+</bookinfo>
+
+<toc></toc> <!-- autogenerated -->
+
+<!-- ADD THE CHAPTERS HERE -->
+  <chapter id="introdution">
+    &sub-intro;
+  </chapter>
+  <chapter id="frontend">
+    &sub-frontend;
+  </chapter>
+  <chapter id="demux">
+    &sub-demux;
+  </chapter>
+  <chapter id="video">
+    &sub-video;
+  </chapter>
+  <chapter id="audio">
+    &sub-audio;
+  </chapter>
+  <chapter id="ca">
+    &sub-ca;
+  </chapter>
+  <chapter id="net">
+    &sub-net;
+  </chapter>
+  <chapter id="kdapi">
+    &sub-kdapi;
+  </chapter>
+  <chapter id="examples">
+    &sub-examples;
+  </chapter>
+<!-- END OF CHAPTERS -->
+  &sub-fdl-appendix;
+
+</book>