@@ -1,5 +1,9 @@
bsd-core/*/@
bsd-core/*/machine
+*.1
+*.3
+*.5
+*.7
*.flags
*.ko
*.ko.cmd
@@ -35,27 +35,6 @@ AM_MAINTAINER_MODE([enable])
# Enable quiet compiles on automake 1.11.
m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
-if test x$LIB_MAN_SUFFIX = x ; then
- LIB_MAN_SUFFIX=3
-fi
-if test x$LIB_MAN_DIR = x ; then
- LIB_MAN_DIR='$(mandir)/man$(LIB_MAN_SUFFIX)'
-fi
-AC_SUBST([LIB_MAN_SUFFIX])
-AC_SUBST([LIB_MAN_DIR])
-
-MAN_SUBSTS="\
- -e 's|__vendorversion__|\"\$(PACKAGE_STRING)\" |' \
- -e 's|__projectroot__|\$(prefix)|g' \
- -e 's|__apploaddir__|\$(appdefaultdir)|g' \
- -e 's|__appmansuffix__|\$(APP_MAN_SUFFIX)|g' \
- -e 's|__drivermansuffix__|\$(DRIVER_MAN_SUFFIX)|g' \
- -e 's|__adminmansuffix__|\$(ADMIN_MAN_SUFFIX)|g' \
- -e 's|__libmansuffix__|\$(LIB_MAN_SUFFIX)|g' \
- -e 's|__miscmansuffix__|\$(MISC_MAN_SUFFIX)|g' \
- -e 's|__filemansuffix__|\$(FILE_MAN_SUFFIX)|g'"
-AC_SUBST([MAN_SUBSTS])
-
# Check for programs
AC_PROG_CC
@@ -235,6 +214,9 @@ if test "x$HAVE_LIBUDEV" = xyes; then
fi
AM_CONDITIONAL(HAVE_LIBUDEV, [test "x$HAVE_LIBUDEV" = xyes])
+AC_PATH_PROG(XSLTPROC, xsltproc)
+AM_CONDITIONAL([HAVE_XSLTPROC], [test "x$XSLTPROC" != "x"])
+
if test "x$INTEL" != "xno" -o "x$RADEON" != "xno" -o "x$NOUVEAU" != "xno" -o "x$OMAP" != "xno"; then
# Check for atomic intrinsics
AC_CACHE_CHECK([for native atomic primitives], drm_cv_atomic_primitives,
@@ -1,11 +1,47 @@
-libmandir = $(LIB_MAN_DIR)
-libman_PRE = drmAvailable.man \
- drmHandleEvent.man \
- drmModeGetResources.man
-libman_DATA = $(libman_PRE:man=@LIB_MAN_SUFFIX@)
-EXTRA_DIST = $(libman_PRE)
-CLEANFILE = $(libman_DATA)
-SUFFIXES = .$(LIB_MAN_SUFFIX) .man
-
-.man.$(LIB_MAN_SUFFIX):
- $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@
+#
+# This generates man-pages out of the Docbook XML files. Simply add your files
+# to the $MANPAGES array. If aliases are created, please add them to the
+# MANPAGES_ALIASES array so they get installed correctly.
+#
+
+MANPAGES = \
+ drmAvailable.3 \
+ drmHandleEvent.3 \
+ drmModeGetResources.3
+MANPAGES_ALIASES =
+
+XML_FILES = \
+ ${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,$(MANPAGES)}}}}
+CLEANFILES =
+EXTRA_DIST =
+man_MANS =
+
+if HAVE_XSLTPROC
+
+CLEANFILES += $(MANPAGES) $(MANPAGES_ALIASES)
+EXTRA_DIST += $(MANPAGES) $(MANPAGES_ALIASES) $(XML_FILES)
+man_MANS += $(MANPAGES) $(MANPAGES_ALIASES)
+
+XSLTPROC_FLAGS = \
+ --stringparam man.authors.section.enabled 0 \
+ --stringparam man.copyright.section.enabled 0 \
+ --stringparam funcsynopsis.style ansi \
+ --stringparam man.output.quietly 1
+
+XSLTPROC_PROCESS_MAN = \
+ $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
+ $(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+
+%.1: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+%.3: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+%.5: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+%.7: %.xml
+ $(XSLTPROC_PROCESS_MAN)
+
+endif # HAVE_XSLTPROC
deleted file mode 100644
@@ -1,25 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH drmAvailable __drivermansuffix__ __vendorversion__
-.SH NAME
-drmAvailable \- determine whether a DRM kernel driver has been loaded
-.SH SYNOPSIS
-.nf
-.B "#include <xf86drm.h>"
-
-.B "int drmAvailable(void);"
-.fi
-.SH DESCRIPTION
-This function allows the caller to determine whether a kernel DRM driver is
-loaded.
-
-.SH RETURN VALUE
-If a DRM driver is currently loaded, this function returns 1. Otherwise 0
-is returned.
-
-.SH REPORTING BUGS
-Bugs in this function should be reported to http://bugs.freedesktop.org under
-the "Mesa" product, with "Other" or "libdrm" as the component.
-
-.SH "SEE ALSO"
-drmOpen(__libmansuffix__)
new file mode 100644
@@ -0,0 +1,75 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drmAvailable">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drmAvailable</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drmAvailable</refname>
+ <refpurpose>determine whether a DRM kernel driver has been
+ loaded</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <funcsynopsis>
+
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>drmAvailable</function></funcdef>
+ <paramdef>void</paramdef>
+ </funcprototype>
+
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para><function>drmAvailable</function> allows the caller to determine
+ whether a kernel DRM driver is loaded.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+ <para><function>drmAvailable</function> returns 1 if a DRM driver is
+ currently loaded. Otherwise 0 is returned.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this function should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmOpen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
deleted file mode 100644
@@ -1,45 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH drmHandleEvent __drivermansuffix__ __vendorversion__
-.SH NAME
-drmHandleEvent \- read and process pending DRM events
-.SH SYNOPSIS
-.nf
-.B "#include <xf86drm.h>"
-
-.B "typedef struct _drmEventContext {"
-.BI " int version;"
-.BI " void (*vblank_handler)(int fd,"
-.BI " unsigned int sequence,"
-.BI " unsigned int tv_sec,"
-.BI " unsigned int tv_usec,"
-.BI " void *user_data);"
-.BI " void (*page_flip_handler)(int fd,"
-.BI " unsigned int sequence,"
-.BI " unsigned int tv_sec,"
-.BI " unsigned int tv_usec,"
-.BI " void *user_data);"
-.B "} drmEventContext, *drmEventContextPtr;"
-
-.B "int drmHandleEvent(int fd, drmEventContextPtr evctx);"
-.fi
-.SH DESCRIPTION
-This function will process outstanding DRM events on
-.I fd
-, which must be an open DRM device. This function should be called after
-the DRM file descriptor has polled readable; it will read the events and
-use the passed-in
-.I evctx
-structure to call function pointers with the parameters noted above.
-
-.SH RETURN VALUE
-Returns 0 on success, or if there is no data to read from the file descriptor.
-Returns -1 if the read on the file descriptor fails or returns less than a
-full event record.
-
-.SH REPORTING BUGS
-Bugs in this function should be reported to http://bugs.freedesktop.org under
-the "Mesa" product, with "Other" or "libdrm" as the component.
-
-.SH "SEE ALSO"
-drmModePageFlip(__libmansuffix__), drmWaitVBlank(__libmansuffix__)
new file mode 100644
@@ -0,0 +1,102 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drmHandleEvent">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drmHandleEvent</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drmHandleEvent</refname>
+ <refpurpose>read and process pending DRM events</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>int <function>drmHandleEvent</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ <paramdef>drmEventContextPtr <parameter>evctx</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para><function>drmHandleEvent</function> processes outstanding DRM events
+ on the DRM file-descriptor passed as <parameter>fd</parameter>. This
+ function should be called after the DRM file-descriptor has polled
+ readable; it will read the events and use the passed-in
+ <parameter>evctx</parameter> structure to call function pointers
+ with the parameters noted below:
+
+<programlisting>
+typedef struct _drmEventContext {
+ int version;
+ void (*vblank_handler) (int fd,
+ unsigned int sequence,
+ unsigned int tv_sec,
+ unsigned int tv_usec,
+ void *user_data)
+ void (*page_flip_handler) (int fd,
+ unsigned int sequence,
+ unsigned int tv_sec,
+ unsigned int tv_usec,
+ void *user_data)
+} drmEventContext, *drmEventContextPtr;
+</programlisting>
+
+ </para>
+
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+ <para><function>drmHandleEvent</function> returns <literal>0</literal> on
+ success, or if there is no data to read from the file-descriptor.
+ Returns <literal>-1</literal> if the read on the file-descriptor fails
+ or returns less than a full event record.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this function should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModePageFlip</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmWaitVBlank</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
deleted file mode 100644
@@ -1,79 +0,0 @@
-.\" shorthand for double quote that works everywhere.
-.ds q \N'34'
-.TH drmModeGetResources __drivermansuffix__ __vendorversion__
-.SH NAME
-drmModeGetResources \- retrieve current display configuration information
-.SH SYNOPSIS
-.nf
-.B "#include <xf86drmMode.h>"
-
-.BI "typedef struct _drmModeRes {"
-
-.BI " int count_fbs;"
-.BI " uint32_t *fbs;"
-
-.BI " int count_crtcs;"
-.BI " uint32_t *crtcs;"
-
-.BI " int count_connectors;"
-.BI " uint32_t *connectors;"
-
-.BI " int count_encoders;"
-.BI " uint32_t *encoders;"
-
-.BI " uint32_t min_width, max_width;"
-.BI " uint32_t min_height, max_height;"
-.B "} drmModeRes, *drmModeResPtr;"
-
-.B "drmModeResPtr drmModeGetResources(int fd);"
-.fi
-.SH DESCRIPTION
-This function will allocate, populate, and return a drmModeRes structure
-containing information about the current display configuration.
-
-The
-.I count_fbs
-and
-.I fbs
-fields indicate the number of currently allocated framebuffer objects (i.e.
-objects that can be attached to a given CRTC or sprite for display).
-
-The
-.I count_crtcs
-and
-.I crtcs
-fields list the available CRTCs in the configuration. A CRTC is simply
-an object that can scan out a framebuffer to a display sink, and contains
-mode timing and relative position information. CRTCs drive encoders, which
-are responsible for converting the pixel stream into a specific display
-protocol (e.g. MIPI or HDMI).
-
-The
-.I count_connectors
-and
-.I connectors
-fields list the available physical connectors on the system. Note that
-some of these may not be exposed from the chassis (e.g. LVDS or eDP).
-Connectors are attached to encoders and contain information about the
-attached display sink (e.g. width and height in mm, subpixel ordering, and
-various other properties).
-
-The
-.I count_encoders
-and
-.I encoders
-fields list the available encoders on the device. Each encoder may be
-associated with a CRTC, and may be used to drive a particular encoder.
-
-The min and max height fields indicate the maximum size of a framebuffer
-for this device (i.e. the scanout size limit).
-
-.SH RETURN VALUE
-Returns a drmModeRes structure pointer on success, 0 on failure.
-
-.SH REPORTING BUGS
-Bugs in this function should be reported to http://bugs.freedesktop.org under
-the "Mesa" product, with "Other" or "libdrm" as the component.
-
-.SH "SEE ALSO"
-drmModeGetFB(__libmansuffix__), drmModeAddFB(__libmansuffix__), drmModeAddFB2(__libmansuffix__), drmModeRmFB(__libmansuffix__), drmModeDirtyFB(__libmansuffix__), drmModeGetCrtc(__libmansuffix__), drmModeSetCrtc(__libmansuffix__), drmModeGetEncoder(__libmansuffix__), drmModeGetConnector(__libmansuffix__)
new file mode 100644
@@ -0,0 +1,139 @@
+<?xml version='1.0'?> <!--*-nxml-*-->
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<!--
+ Written 2012 by David Herrmann <dh.herrmann@googlemail.com>
+ Dedicated to the Public Domain
+-->
+
+<refentry id="drmModeGetResources">
+ <refentryinfo>
+ <title>Direct Rendering Manager</title>
+ <productname>libdrm</productname>
+ <date>September 2012</date>
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>David</firstname>
+ <surname>Herrmann</surname>
+ <email>dh.herrmann@googlemail.com</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>drmModeGetResources</refentrytitle>
+ <manvolnum>3</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>drmModeGetResources</refname>
+ <refpurpose>retrieve current display configuration information</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+
+ <funcsynopsis>
+ <funcsynopsisinfo>#include <xf86drm.h></funcsynopsisinfo>
+ <funcsynopsisinfo>#include <xf86drmMode.h></funcsynopsisinfo>
+
+ <funcprototype>
+ <funcdef>drmModeResPtr <function>drmModeGetResources</function></funcdef>
+ <paramdef>int <parameter>fd</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+ <para><function>drmModeGetResources</function> allocates, populates, and
+ returns a <structname>drmModeRes</structname> structure containing
+ information about the current display configuration. The structure
+ contains the following fields:
+
+<programlisting>
+typedef struct _drmModeRes {
+ int count_fbs;
+ uint32_t *fbs;
+
+ int count_crtcs;
+ uint32_t *crtcs;
+
+ int count_connectors;
+ uint32_t *connectors;
+
+ int count_encoders;
+ uint32_t *encoders;
+
+ uint32_t min_width, max_width;
+ uint32_t min_height, max_height;
+} drmModeRes, *drmModeResPtr;
+</programlisting>
+
+ </para>
+
+ <para>The <structfield>count_fbs</structfield> and
+ <structfield>fbs</structfield> fields indicate the number of currently
+ allocated framebuffer objects (i.e., objects that can be attached to
+ a given CRTC or sprite for display).</para>
+
+ <para>The <structfield>count_crtcs</structfield> and
+ <structfield>crtcs</structfield> fields list the available CRTCs in
+ the configuration. A CRTC is simply an object that can scan out a
+ framebuffer to a display sink, and contains mode timing and relative
+ position information. CRTCs drive encoders, which are responsible for
+ converting the pixel stream into a specific display protocol (e.g.,
+ MIPI or HDMI).</para>
+
+ <para>The <structfield>count_connectors</structfield> and
+ <structfield>connectors</structfield> fields list the available
+ physical connectors on the system. Note that some of these may not be
+ exposed from the chassis (e.g., LVDS or eDP). Connectors are attached
+ to encoders and contain information about the attached display sink
+ (e.g., width and height in mm, subpixel ordering, and various other
+ properties).</para>
+
+ <para>The <structfield>count_encoders</structfield> and
+ <structfield>encoders</structfield> fields list the available encoders
+ on the device. Each encoder may be associated with a CRTC, and may be
+ used to drive a particular encoder.</para>
+
+ <para>The <structfield>min*</structfield> and
+ <structfield>max*</structfield> fields indicate the maximum size of a
+ framebuffer for this device (i.e., the scanout size limit).</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Return Value</title>
+ <para><function>drmModeGetResources</function> returns a drmModeRes
+ structure pointer on success, <literal>NULL</literal> on failure. The
+ returned structure must be freed with
+ <citerefentry><refentrytitle>drmModeFreeResources</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Reporting Bugs</title>
+ <para>Bugs in this function should be reported to
+ http://bugs.freedesktop.org under the "Mesa" product, with "Other" or
+ "libdrm" as the component.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>drm</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drm-kms</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeAddFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeAddFB2</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeRmFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeDirtyFB</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeSetCrtc</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetEncoder</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>drmModeGetConnector</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ </para>
+ </refsect1>
+</refentry>
If we want to use the manpages in external documentation other than normal manpages, we should rather use XML. Furthermore, almost no-one knows troff today, anyway, and XML allows others to easily add more pages without having to learn troff. Signed-off-by: David Herrmann <dh.herrmann@googlemail.com> --- .gitignore | 4 ++ configure.ac | 24 +------- man/Makefile.am | 58 ++++++++++++++---- man/drmAvailable.man | 25 -------- man/drmAvailable.xml | 75 ++++++++++++++++++++++++ man/drmHandleEvent.man | 45 -------------- man/drmHandleEvent.xml | 102 ++++++++++++++++++++++++++++++++ man/drmModeGetResources.man | 79 ------------------------- man/drmModeGetResources.xml | 139 ++++++++++++++++++++++++++++++++++++++++++++ 9 files changed, 370 insertions(+), 181 deletions(-) delete mode 100644 man/drmAvailable.man create mode 100644 man/drmAvailable.xml delete mode 100644 man/drmHandleEvent.man create mode 100644 man/drmHandleEvent.xml delete mode 100644 man/drmModeGetResources.man create mode 100644 man/drmModeGetResources.xml