Add Man pages in RONN format

man/.gitignore

@@ -0,0 +1,7 @@
+# Ignore generated man pages
+*.1
+*.3
+
+# Ignore generated html pages
+*.html
+

man/Makefile

@@ -0,0 +1,14 @@
+# Makefile to generate man & html pages from ronn input
+# This is deliberately kept as a manual makefile and not as a part of
+# the autotools framework for the time being.
+
+PROJECT := x52pro-linux
+
+MAN3_PAGES := $(wildcard *.3.ronn)
+all: $(MAN3_PAGES)
+	ronn --manual "Programmer's Guide" --organization="$(PROJECT)" $(MAN3_PAGES)
+
+.PHONY: clean
+clean:
+	rm -f *.3
+	rm -f *.html

man/README.md

@@ -0,0 +1,9 @@
+Man Pages for x52pro-linux
+==========================
+
+This folder contains the man pages for the components of libx52 in a Markdown
+format called ronn. To convert them into man pages requires the ronn executable,
+which may be found in the ruby-ronn package on Ubuntu. Other distributions may
+have a similar package name.
+
+ronn may also be found at http://github.com/rtomayko/ronn

man/index.txt

@@ -0,0 +1,5 @@
+# Standard POSIX manuals
+time(2)                     http://man.cx/time%282%29
+localtime(3)                http://man.cx/localtime
+gmtime(3)                   http://man.cx/gmtime
+timezone(3)                 http://man.cx/tzset

man/libx52_exit.3.ronn

@@ -0,0 +1,18 @@
+libx52_exit(3) -- exit the library and free up any resources used
+=================================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+**void libx52_exit(libx52_device * _dev_)**
+
+## DESCRIPTION
+
+`libx52_exit()` releases any resources allocated by libx52_init(3) and
+terminates the library. Using the freed device now is invalid and can cause
+errors.
+
+## SEE ALSO
+
+libx52_init(3)

man/libx52_init.3.ronn

@@ -0,0 +1,27 @@
+libx52_init(3) -- Initialize libx52
+===================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`libx52_device * libx52_init(void)`
+
+## DESCRIPTION
+
+`libx52_init()` initializes the libx52 library, sets up any internal data
+structures to access the X52 Pro joystick and returns a *libx52_device* pointer.
+
+If no joystick is found `libx52_init()` returns _NULL_.
+
+## LIMITATIONS
+
+`libx52_init()` currently only recognizes the Saitek X52 Pro, not the original
+Saitek X52.
+
+`libx52_init()` does not support hotplugging. The joystick must be plugged in
+before calling this function.
+
+## SEE ALSO
+
+libx52_exit(3)

man/libx52_set_blink.3.ronn

@@ -0,0 +1,21 @@
+libx52_set_blink(3) -- turn the blink module on or off
+======================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_blink(libx52_device *` _x52_`, uint8_t ` _state_`)`
+
+## DESCRIPTION
+
+`libx52_set_blink()` can be used to set the state of the blink module to `on`
+(_state_ is non-zero) or `off` (_state_ is 0).
+
+## RETURN VALUE
+
+`libx52_set_blink()` returns 0 on success, and `-EINVAL` if _x52_ is not valid.
+
+## SEE ALSO
+
+libx52_update(3)

man/libx52_set_brightness.3.ronn

@@ -0,0 +1,25 @@
+libx52_set_brightness(3) -- set the brightness of the MFD or LEDs
+=================================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_brightness(libx52_device *` _x52_`, uint8_t ` _mfd_
+`, uint16_t ` _brightness_`)`
+
+## DESCRIPTION
+
+`libx52_set_brightness()` can be used to set the brightness of the MFD (if _mfd_
+is non-zero) or the LEDs (if _mfd_ is *0*). Brightness should be a value
+between 0 and 128. While higher values are accepted, they do not have the
+intended effect.
+
+## RETURN VALUE
+
+`libx52_set_brightness()` returns 0 on success, and `-EINVAL` if _x52_ is not
+valid.
+
+## SEE ALSO
+
+libx52_set_text(3), libx52_set_led_state(3), libx52_update(3)

man/libx52_set_clock.3.ronn

@@ -0,0 +1,37 @@
+libx52_set_clock(3) -- set the primary clock
+============================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_clock(libx52_device *` _x52_`, time_t ` _time_ `, int ` _local_`)`
+
+## DESCRIPTION
+
+`libx52_set_clock()` can be used to set the primary clock and date display of
+the MFD.  The _time_ can be obtained from time(2). _local_ controls whether
+the primary clock displays local time or GMT.
+
+If this function is called again within the same minute as calculated by
+localtime(3) or gmtime(3), it will return `-EAGAIN`, as it does not require
+any updates to be written to the X52 Pro. However, if the call changes the
+timezone from local time to GMT or vice-versa, then this function will return
+0, since it necessitates a write to the device to update the clock with the
+new timezone.
+
+The secondary and tertiary clocks are driven off the primary clock and set as
+offsets in minutes east of GMT.
+
+## RETURN VALUE
+
+`libx52_set_clock()` returns the following values:
+
+* 0 on success
+* `-EINVAL` if _x52_ is not valid
+* `-EAGAIN` if the time did not require an update to the clock.
+
+## SEE ALSO
+
+libx52_set_clock_timezone(3), libx52_set_clock_format(3),
+libx52_set_date_format(3), libx52_update(3)

man/libx52_set_clock_format.3.ronn

@@ -0,0 +1,42 @@
+libx52_set_clock_format(3) -- set the clock display format
+==========================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_clock_format(libx52_device *` _x52_`, libx52_clock_id `
+_clock_ `, libx52_clock_format ` _format_`)`
+
+## DESCRIPTION
+
+`libx52_set_clock_format()` can be used to set the clocks to display in 12hr
+or 24hr format.
+
+### CLOCK IDS
+
+The following are the clocks supported by the X52 Pro MFD:
+
+* `LIBX52_CLOCK_1` - refers to the primary clock
+* `LIBX52_CLOCK_2` - refers to the secondary clock
+* `LIBX52_CLOCK_3` - refers to the tertiary clock
+
+### CLOCK FORMATS
+
+The following formats are supported by the X52 Pro MFD:
+
+* `LIBX52_CLOCK_FORMAT_12HR`
+* `LIBX52_CLOCK_FORMAT_24HR`
+
+## RETURN VALUE
+
+`libx52_set_clock_format()` returns the following values:
+
+* 0 on success
+* `-EINVAL` if _x52_ is not valid, or _clock_ or _format_ values are not in
+the accepted range
+
+## SEE ALSO
+
+libx52_set_clock(3), libx52_set_clock_timezone(3),
+libx52_set_date_format(3), libx52_update(3)

man/libx52_set_clock_timezone.3.ronn

@@ -0,0 +1,34 @@
+libx52_set_clock_timezone(3) -- set the timezone for the secondary and tertiary clocks
+======================================================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_clock_timezone(libx52_device *` _x52_`, libx52_clock_id `
+_clock_ `, int ` _offset_`)`
+
+## DESCRIPTION
+
+`libx52_set_clock_timezone()` can be used to set the timezone for the secondary
+and tertiary clocks on the MFD. The timezone is set as an _offset_ in minutes
+east of GMT. Note that this is different from the timezone(3) attribute in the
+standard C library which specifies the offset in seconds west of GMT.
+
+_offset_ is limited to +/- 24 hours (1440 minutes).
+
+See libx52_set_clock_format(3) for an explanation of `libx52_clock_id`.
+
+## RETURN VALUE
+
+`libx52_set_clock()` returns the following values:
+
+* 0 on success
+* `-EINVAL` if _x52_ is not valid
+* `-EDOM` if the offset is more than +/- 24 hours
+* `-ENOTSUP` if the _clock_ is `LIBX52_CLOCK_1`
+
+## SEE ALSO
+
+libx52_set_clock(3), libx52_set_clock_format(3),
+libx52_set_date_format(3), libx52_update(3)

man/libx52_set_date_format.3.ronn

@@ -0,0 +1,32 @@
+libx52_set_date_format(3) -- set the date display format
+==========================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_date_format(libx52_device *` _x52_`, libx52_date_format ` _format_`)`
+
+## DESCRIPTION
+
+`libx52_set_date_format()` can be used to set the date display format.
+
+### DATE FORMATS
+
+The following formats are supported by the X52 Pro MFD:
+
+* `LIBX52_DATE_FORMAT_DDMMYY`
+* `LIBX52_DATE_FORMAT_MMDDYY`
+* `LIBX52_DATE_FORMAT_YYMMDD`
+
+## RETURN VALUE
+
+`libx52_set_date_format()` returns the following values:
+
+* 0 on success
+* `-EINVAL` if _x52_ is not valid
+
+## SEE ALSO
+
+libx52_set_clock(3), libx52_set_clock_timezone(3), libx52_set_clock_format(3),
+libx52_update(3)

man/libx52_set_led_state.3.ronn

@@ -0,0 +1,58 @@
+libx52_set_led_state(3) -- set the LED state
+============================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_led_state(libx52_device *`_x52_`, libx52_led_id ` _led_
+`, libx52_led_state ` _state_`)`
+
+## DESCRIPTION
+
+The Saitek X52 Pro has several LEDs that can be individually controlled. This
+function allows you to set the state of each LED in the internal data
+structures.
+
+### LED STATES
+
+The following are the supported LED states that are accepted by the _state_
+parameter. Note that all values are not supported by all LEDs.
+
+* `LIBX52_LED_STATE_OFF`
+* `LIBX52_LED_STATE_ON`
+* `LIBX52_LED_STATE_RED`
+* `LIBX52_LED_STATE_AMBER`
+* `LIBX52_LED_STATE_GREEN`
+
+### LED IDS
+
+The following are the supported LED identifiers that are accepted by the _led_
+parameter:
+
+* `LIBX52_LED_FIRE`
+* `LIBX52_LED_A`
+* `LIBX52_LED_B`
+* `LIBX52_LED_D`
+* `LIBX52_LED_E`
+* `LIBX52_LED_T1`
+* `LIBX52_LED_T2`
+* `LIBX52_LED_T3`
+* `LIBX52_LED_POV`
+* `LIBX52_LED_CLUTCH`
+* `LIBX52_LED_THROTTLE`
+
+Note that the LEDs referred to by `LIBX52_LED_FIRE` and `LIBX52_LED_THROTTLE`
+support only the states `LIBX52_LED_STATE_OFF` and `LIBX52_LED_STATE_ON`. The
+remaining LEDs support all the states with the exception of
+`LIBX52_LED_STATE_ON`.
+
+## RETURN VALUES
+
+`libx52_led_state()` returns 0 on success, `-EINVAL` if the _x52_ parameter is
+not valid, and `-ENOTSUP` if the _led_ and _state_ combination is not a
+supported one.
+
+## SEE ALSO
+
+libx52_update(3)

man/libx52_set_shift.3.ronn

@@ -0,0 +1,21 @@
+libx52_set_shift(3) -- turn the shift indicator on or off
+=========================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_shift(libx52_device *` _x52_`, uint8_t ` _state_`)`
+
+## DESCRIPTION
+
+`libx52_set_shift()` can be used to set the state of the shift indicator on the
+MFD to `on` (_state_ is non-zero) or `off` (_state_ is 0).
+
+## RETURN VALUE
+
+`libx52_set_shift()` returns 0 on success, and `-EINVAL` if _x52_ is not valid.
+
+## SEE ALSO
+
+libx52_update(3)

man/libx52_set_text.3.ronn

@@ -0,0 +1,35 @@
+libx52_set_text(3) -- set the text on an MFD line
+=================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_set_text(libx52_device *` _x52_`, uint8_t` _line_`, const char *`
+_text_`, uint8_t` _length_`)`
+
+## DESCRIPTION
+
+The Multifunction display (MFD) on the Saitek X52 Pro supports 3 lines of up to
+16 characters. This function will set the text into the internal data
+structures.
+
+_text_ must be a pointer to an array of bytes, each byte represents a code point
+on the MFD's internal character map. _length_ is the length of this array.
+
+_line_ must be **0**, **1** or **2** and refers to the first, second or third
+line of the MFD respectively. _x52_ is a pointer returned by libx52_init(3).
+
+## RETURN VALUE
+
+`libx52_set_text()` returns 0 on success, and `-EINVAL` if either _x52_ is
+invalid, or _line_ is outside of the accepted range.
+
+## LIMITATIONS
+
+`libx52_set_text()` can only store a maximum of 16 characters. Any additional
+characters are discarded.
+
+## SEE ALSO
+
+libx52_update(3)

man/libx52_update.3.ronn

@@ -0,0 +1,19 @@
+libx52_update(3) -- update the X52 Pro
+======================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_update(libx52_device *` _x52_`)`
+
+## DESCRIPTION
+
+All the standard `libx52_set_*` functions only set the internal data structures,
+but do not actually write anything to the joystick. This function writes the
+saved data to the joystick and resets the internal data structures.
+
+## RETURN VALUE
+
+`libx52_update()` returns 0 on success, and a non-zero error number on failure.
+

man/libx52_vendor_command.3.ronn

@@ -0,0 +1,27 @@
+libx52_vendor_command(3) -- write a raw vendor control packet
+=============================================================
+
+## SYNOPSIS
+
+`#include <libx52.h>`
+
+`int libx52_vendor_command(libx52_device *` _x52_`, uint16_t ` _wIndex_
+`, uint16_t ` _wValue_ `)`
+
+## DESCRIPTION
+
+`libx52_vendor_command()` can be used to debug issues seen on the hardware,
+however, it is not recommended for use by end users, as it can potentially
+damage the hardware.
+
+## RETURN VALUE
+
+`libx52_vendor_command()` returns 0 on success, and a non-zero error number on
+failure.
+
+## SEE ALSO
+
+libx52_set_text(3), libx52_set_led_state(3), libx52_set_clock(3),
+libx52_set_clock_timezone(3), libx52_set_clock_format(3),
+libx52_set_date_format(3), libx52_set_brightness(3), libx52_set_shift(3),
+libx52_set_blink(3), libx52_update(3)