From 6b7e45c7516b7fdfe85e7792f82624458dcb2ac6 Mon Sep 17 00:00:00 2001 From: David Herrmann Date: Fri, 28 Sep 2012 23:44:19 +0200 Subject: [PATCH] man: convert manpages to XML instead of plain troff 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 --- .gitignore | 4 ++ configure.ac | 24 +------ man/Makefile.am | 56 ++++++++++++--- 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, 369 insertions(+), 180 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 28c77c53..1de66bca 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 0c19929d..0e6db862 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 @@ -247,6 +226,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 ccd6545c..b93fdef8 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) -CLEANFILES = $(libman_DATA) -SUFFIXES = .$(LIB_MAN_SUFFIX) .man +# +# 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. +# -.man.$(LIB_MAN_SUFFIX): - $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@ +MANPAGES = \ + drmAvailable.3 \ + drmHandleEvent.3 \ + drmModeGetResources.3 +MANPAGES_ALIASES = + +XML_FILES = \ + ${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubs %.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 e1bb8dc8..00000000 --- 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 " - -.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 00000000..55bef94a --- /dev/null +++ b/man/drmAvailable.xml @@ -0,0 +1,75 @@ + + + + + + + + Direct Rendering Manager + libdrm + September 2012 + + + Developer + David + Herrmann + dh.herrmann@googlemail.com + + + + + + drmAvailable + 3 + + + + drmAvailable + determine whether a DRM kernel driver has been + loaded + + + + + + #include <xf86drm.h> + + + int drmAvailable + void + + + + + + + Description + drmAvailable allows the caller to determine + whether a kernel DRM driver is loaded. + + + + Return Value + drmAvailable returns 1 if a DRM driver is + currently loaded. Otherwise 0 is returned. + + + + 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. + + + + See Also + + drm7, + drmOpen3 + + + diff --git a/man/drmHandleEvent.man b/man/drmHandleEvent.man deleted file mode 100644 index b98f417d..00000000 --- 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 " - -.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 00000000..b1006e51 --- /dev/null +++ b/man/drmHandleEvent.xml @@ -0,0 +1,102 @@ + + + + + + + + Direct Rendering Manager + libdrm + September 2012 + + + Developer + David + Herrmann + dh.herrmann@googlemail.com + + + + + + drmHandleEvent + 3 + + + + drmHandleEvent + read and process pending DRM events + + + + + + #include <xf86drm.h> + + + int drmHandleEvent + int fd + drmEventContextPtr evctx + + + + + + + Description + drmHandleEvent processes outstanding DRM events + on the DRM file-descriptor passed as fd. This + function should be called after the DRM file-descriptor has polled + readable; it will read the events and use the passed-in + evctx structure to call function pointers + with the parameters noted below: + + +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; + + + + + + + + Return Value + drmHandleEvent 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. + + + + 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. + + + + See Also + + drm7, + drm-kms7, + drmModePageFlip3, + drmWaitVBlank3 + + + diff --git a/man/drmModeGetResources.man b/man/drmModeGetResources.man deleted file mode 100644 index 369bf7d8..00000000 --- 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 " - -.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 00000000..2f5e8c2c --- /dev/null +++ b/man/drmModeGetResources.xml @@ -0,0 +1,139 @@ + + + + + + + + Direct Rendering Manager + libdrm + September 2012 + + + Developer + David + Herrmann + dh.herrmann@googlemail.com + + + + + + drmModeGetResources + 3 + + + + drmModeGetResources + retrieve current display configuration information + + + + + + #include <xf86drm.h> + #include <xf86drmMode.h> + + + drmModeResPtr drmModeGetResources + int fd + + + + + + + Description + drmModeGetResources allocates, populates, and + returns a drmModeRes structure containing + information about the current display configuration. The structure + contains the following fields: + + +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; + + + + + The count_fbs and + 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 count_crtcs and + 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 count_connectors and + 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 count_encoders and + 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* fields indicate the maximum size of a + framebuffer for this device (i.e., the scanout size limit). + + + + Return Value + drmModeGetResources returns a drmModeRes + structure pointer on success, NULL on failure. The + returned structure must be freed with + drmModeFreeResources3. + + + + 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. + + + + See Also + + drm7, + drm-kms7, + drmModeGetFB3, + drmModeAddFB3, + drmModeAddFB23, + drmModeRmFB3, + drmModeDirtyFB3, + drmModeGetCrtc3, + drmModeSetCrtc3, + drmModeGetEncoder3, + drmModeGetConnector3 + + +