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
diff --git a/.gitignore b/.gitignore index 243457e..d297f94 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,9 @@ bsd-core/*/@ bsd-core/*/machine +*.1 +*.3 +*.5 +*.7 *.flags *.ko *.ko.cmd diff --git a/configure.ac b/configure.ac index 290362c..7fd7f11 100644 --- a/configure.ac +++ b/configure.ac @@ -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, diff --git a/man/Makefile.am b/man/Makefile.am index 73068e6..3030e5f 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -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 diff --git a/man/drmAvailable.man b/man/drmAvailable.man deleted file mode 100644 index e1bb8dc..0000000 --- a/man/drmAvailable.man +++ /dev/null @@ -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__) diff --git a/man/drmAvailable.xml b/man/drmAvailable.xml new file mode 100644 index 0000000..55bef94 --- /dev/null +++ b/man/drmAvailable.xml @@ -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> diff --git a/man/drmHandleEvent.man b/man/drmHandleEvent.man deleted file mode 100644 index b98f417..0000000 --- a/man/drmHandleEvent.man +++ /dev/null @@ -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__) diff --git a/man/drmHandleEvent.xml b/man/drmHandleEvent.xml new file mode 100644 index 0000000..b1006e5 --- /dev/null +++ b/man/drmHandleEvent.xml @@ -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> diff --git a/man/drmModeGetResources.man b/man/drmModeGetResources.man deleted file mode 100644 index 369bf7d..0000000 --- a/man/drmModeGetResources.man +++ /dev/null @@ -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__) diff --git a/man/drmModeGetResources.xml b/man/drmModeGetResources.xml new file mode 100644 index 0000000..2f5e8c2 --- /dev/null +++ b/man/drmModeGetResources.xml @@ -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>