mirror of https://github.com/nirenjan/libx52.git
Move x52cli documentation into Doxygen
Prior to this change, the x52cli man page was a manually created file that was out of date with the source. Rather than update that file, and maintain a separate document for the HTML sources, it makes sense to consolidate both the HTML and manpage documentation to a Doxygen page block within the source and update the Doxyfile to generate man pages as well. This change also removes the obsolete manually maintained manpage, and falls back to Doxygen to build and install the manpage.pull/22/head
parent
374fd94fcd
commit
f9be0b3172
11
Doxyfile.in
11
Doxyfile.in
|
|
@ -524,7 +524,7 @@ EXTRACT_ANON_NSPACES = NO
|
|||
# section is generated. This option has no effect if EXTRACT_ALL is enabled.
|
||||
# The default value is: NO.
|
||||
|
||||
HIDE_UNDOC_MEMBERS = NO
|
||||
HIDE_UNDOC_MEMBERS = YES
|
||||
|
||||
# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all
|
||||
# undocumented classes that are normally visible in the class hierarchy. If set
|
||||
|
|
@ -532,14 +532,14 @@ HIDE_UNDOC_MEMBERS = NO
|
|||
# has no effect if EXTRACT_ALL is enabled.
|
||||
# The default value is: NO.
|
||||
|
||||
HIDE_UNDOC_CLASSES = NO
|
||||
HIDE_UNDOC_CLASSES = YES
|
||||
|
||||
# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend
|
||||
# declarations. If set to NO, these declarations will be included in the
|
||||
# documentation.
|
||||
# The default value is: NO.
|
||||
|
||||
HIDE_FRIEND_COMPOUNDS = NO
|
||||
HIDE_FRIEND_COMPOUNDS = YES
|
||||
|
||||
# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any
|
||||
# documentation blocks found inside the body of a function. If set to NO, these
|
||||
|
|
@ -859,6 +859,7 @@ INPUT_ENCODING = UTF-8
|
|||
FILE_PATTERNS = \
|
||||
libx52.h \
|
||||
libx52util.h \
|
||||
x52_cli.c \
|
||||
*.dox
|
||||
|
||||
# The RECURSIVE tag can be used to specify whether or not subdirectories should
|
||||
|
|
@ -1952,7 +1953,7 @@ RTF_SOURCE_CODE = NO
|
|||
# classes and files.
|
||||
# The default value is: NO.
|
||||
|
||||
GENERATE_MAN = NO
|
||||
GENERATE_MAN = YES
|
||||
|
||||
# The MAN_OUTPUT tag is used to specify where the man pages will be put. If a
|
||||
# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
|
||||
|
|
@ -1970,7 +1971,7 @@ MAN_OUTPUT = man
|
|||
# The default value is: .3.
|
||||
# This tag requires that the tag GENERATE_MAN is set to YES.
|
||||
|
||||
MAN_EXTENSION = .3
|
||||
MAN_EXTENSION = .1
|
||||
|
||||
# The MAN_SUBDIR tag determines the name of the directory created within
|
||||
# MAN_OUTPUT in which the man pages are placed. If defaults to man followed by
|
||||
|
|
|
|||
12
Makefile.am
12
Makefile.am
|
|
@ -26,19 +26,23 @@ EXTRA_DIST = \
|
|||
|
||||
# Doxygen support
|
||||
if HAVE_DOXYGEN
|
||||
DXGEN = $(DXGEN_$(V))
|
||||
DXGEN_ = $(DXGEN_$(AM_DEFAULT_VERBOSITY))
|
||||
DXGEN = $(DXGEN_@AM_V@)
|
||||
DXGEN_ = $(DXGEN_@AM_DEFAULT_V@)
|
||||
DXGEN_0 = @printf " DXGEN $<\n";
|
||||
docs/.stamp: Doxyfile
|
||||
$(DXGEN)$(DOXYGEN) $<
|
||||
$(AM_V_at)touch $@
|
||||
|
||||
CLEANFILES = docs
|
||||
|
||||
all-local: docs/.stamp
|
||||
clean-local:
|
||||
rm -rf $(top_builddir)/docs
|
||||
|
||||
# Install Doxygen generated HTML documentation and manpages
|
||||
install-data-local:
|
||||
$(INSTALL) -d $(DESTDIR)$(docdir)
|
||||
rsync -a $(top_builddir)/docs/html $(DESTDIR)$(docdir)
|
||||
|
||||
$(INSTALL) -d $(DESTDIR)$(mandir)/man1
|
||||
$(INSTALL) -D docs/man/man1/x52cli.1 $(DESTDIR)$(mandir)/man1
|
||||
|
||||
endif
|
||||
|
|
|
|||
|
|
@ -12,6 +12,3 @@ bin_PROGRAMS = x52cli
|
|||
x52cli_SOURCES = x52_cli.c
|
||||
x52cli_CFLAGS = @X52_INCLUDE@
|
||||
x52cli_LDADD = ../../lib/libx52/libx52.la
|
||||
|
||||
# Man pages for CLI utility
|
||||
dist_man1_MANS = x52cli.man
|
||||
|
|
|
|||
|
|
@ -6,6 +6,142 @@
|
|||
* SPDX-License-Identifier: GPL-2.0-only WITH Classpath-exception-2.0
|
||||
*/
|
||||
|
||||
/**
|
||||
@page x52cli Command Line Interface to libx52
|
||||
|
||||
\htmlonly
|
||||
<b>x52cli</b> - Command line interface to libx52
|
||||
\endhtmlonly
|
||||
|
||||
# SYNOPSIS
|
||||
<tt>\b x52cli \a commands [\a command-options]</tt>
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
\b x52cli is a command line interface to the X52 library that allows you to set
|
||||
the LEDs and different parameters on the multifunction display (MFD).
|
||||
|
||||
Running \b x52cli without any arguments will display a brief help message.
|
||||
|
||||
# COMMANDS
|
||||
|
||||
Commands are not case sensitive.
|
||||
|
||||
- <tt>\b bri { \b mfd | \b led } < \a brightness >
|
||||
</tt>\n \manonly \fR \endmanonly
|
||||
Set the brightness of the \b MFD or <b>LED</b>s. \a brightness can be any
|
||||
numeric value between 0 and 128. Higher values are accepted, but may not have
|
||||
the desired effect.
|
||||
|
||||
- <tt>\b mfd < \a line > < \a text > </tt>\n \manonly \fR \endmanonly
|
||||
Set the text on the MFD \a line. \a line can be \c 0, \c 1 or \c 2, and refers
|
||||
to the first, second or third line of the multifunction display respectively.
|
||||
\a text cannot have embedded NUL characters (0x00) and must correspond with
|
||||
the character map fo the MFD. \a text should be quoted in order to preserve
|
||||
embedded whitespace. To pass raw hex values, use \b printf(1) as shown in the
|
||||
\ref x52cli_examples section. Note that \a text is limited to a length of 16
|
||||
characters. While you can pass in longer strings, they will be silenty
|
||||
truncated.
|
||||
|
||||
- <tt>\b led < \a led-id > < \a state > </tt>\n \manonly \fR \endmanonly
|
||||
Set the LED \a led-id to \a state. See \ref x52cli_leds for a list of
|
||||
supported values.
|
||||
|
||||
- <tt>\b blink { \b on | \b off } </tt>\n \manonly \fR \endmanonly
|
||||
Turn the \b blink state \b on or \b off.
|
||||
|
||||
- <tt>\b shift { \b on | \b off } </tt>\n \manonly \fR \endmanonly
|
||||
Turn the \b shift indicator in the MFD \b on or \b off.
|
||||
|
||||
- <tt>\b clock { \b local | \b gmt } { \b 12hr | \b 24hr }
|
||||
{ \b ddmmyy | \b mmddyy | \b yymmdd }</tt>\n \manonly \fR \endmanonly
|
||||
Set the clock 1 display to the current \b local or \b GMT time and date.
|
||||
Clock can be configured to display in either \b 12hr or \b 24hr mode. Date
|
||||
can be displayed in one of the following formats: \b DD-MM-YY, \b MM-DD-YY,
|
||||
or \b YY-MM-DD.
|
||||
|
||||
- <tt>\b offset { \b 2 | \b 3 } < \a offset-val >
|
||||
{ \b 12hr | \b 24hr }</tt>\n \manonly \fR \endmanonly
|
||||
Set the offset for clock \b 2 or \b 3 and configure them to display in either
|
||||
\b 12hr or \b 24hr mode. \a offset-val is in minutes east of \b UTC and can
|
||||
range from \a -1440 to \a +1440.
|
||||
|
||||
- <tt>\b time < \a hour > < \a minute >
|
||||
{ \b 12hr | \b 24hr }</tt>\n \manonly \fR \endmanonly
|
||||
Set the time for clock 1 to <em>hour:minute</em> and configure it to display
|
||||
in \b 12hr or \b 24hr mode.
|
||||
|
||||
- <tt>\b date <\a dd > <\a mm > <\a yy>
|
||||
{ \b ddmmyy | \b mmddyy | \b yymmdd }</tt>\n \manonly \fR \endmanonly
|
||||
Set the date on the MFD to the values represented by \a dd, \a mm and \a yy in
|
||||
the requested format.
|
||||
|
||||
- <tt>\b raw < \a wIndex > < \a wValue ></tt>\n \manonly \fR \endmanonly
|
||||
Send a raw vendor control request to the connected joystick.\n
|
||||
\warning You should only use this if you know what you are doing. Sending
|
||||
an invalid control sequence can potentially destroy your device.
|
||||
|
||||
@section x52cli_leds LEDs
|
||||
This is the list of LED IDs and corresponding states supported by the X52 Pro.
|
||||
Note that the \b on state is only allowed for the \b fire and \b throttle LEDs,
|
||||
and they do not support the \b red, \b amber and \b green states. The remaining
|
||||
LEDs do not support the \b on state, but support all the other states.
|
||||
|
||||
\note The \b led command is only supported on the X52 Pro, not on the X52.
|
||||
|
||||
## LED IDs
|
||||
|
||||
- \b fire
|
||||
- \b a
|
||||
- \b b
|
||||
- \b d
|
||||
- \b e
|
||||
- \b t1
|
||||
- \b t2
|
||||
- \b t3
|
||||
- \b pov
|
||||
- \b clutch
|
||||
- \b throttle
|
||||
|
||||
## States
|
||||
|
||||
- \b off
|
||||
- \b on
|
||||
- \b red
|
||||
- \b amber
|
||||
- \b green
|
||||
|
||||
# LIMITATIONS
|
||||
|
||||
\b x52cli does not maintain any state between invocations. As a result the
|
||||
\b clock command will reset the relative offsets for clocks 2 and 3 back to 0
|
||||
and configure them to be in 12 hour mode. To work around this, use the \b date
|
||||
and \b time commands instead to manually configure the date and time.
|
||||
|
||||
# PERMISSIONS
|
||||
|
||||
You must have write permissions to the USB device in order to use the \b libx52
|
||||
library, and by extension, \b x52cli.
|
||||
|
||||
The simplest method to obtain such permissions is to run \b x52cli as root,
|
||||
possibly through \b sudo(8)
|
||||
|
||||
@section x52cli_examples EXAMPLES
|
||||
|
||||
- Turn off the T1 LED.
|
||||
> <tt>\b x52cli led t1 off</tt>
|
||||
|
||||
- Turn the B LED to Amber.
|
||||
> <tt>\b x52cli led B amber</tt>
|
||||
|
||||
- Set line 1 of the MFD to display "Hello World"
|
||||
> <tt>\b x52cli mfd 0 "Hello World"</tt>
|
||||
|
||||
- Set line 2 of the MFD to display "¿Cómo Estás?"
|
||||
> <tt>\b x52cli mfd 1 "$(printf '\\x9FC\\xE2mo Est\\xE0s?')"</tt>
|
||||
|
||||
*/
|
||||
|
||||
#include <stdio.h>
|
||||
#include <stdint.h>
|
||||
#include <stdlib.h>
|
||||
|
|
|
|||
|
|
@ -1,147 +0,0 @@
|
|||
.TH X52CLI 1 2015-12-09 X52Pro-Linux "User Commands"
|
||||
.SH NAME
|
||||
x52cli \- Command line frontend to libx52
|
||||
|
||||
.SH SYNOPSIS
|
||||
.B x52cli
|
||||
<\fIcommands\fR> [\fIcommand-options\fR]
|
||||
|
||||
.SH DESCRIPTION
|
||||
.BR x52cli
|
||||
is a command line frontend to the X52 library that allows you to set the LEDs
|
||||
and different parameters on the multi-function display.
|
||||
|
||||
Running
|
||||
.BR x52cli
|
||||
without any arguments will display a brief help message.
|
||||
|
||||
.SH COMMANDS
|
||||
Commands are not case sensitive.
|
||||
|
||||
.IP "\fBbri\fR {\fBmfd\fR | \fBled\fR} <\fIbrightness\fR>"
|
||||
Set the brightness of the \fBmfd\fR or \fBled\fRs. \fIbrightness\fR can be any
|
||||
numeric value between 0 and 128. Higher values are accepted, but may not have
|
||||
the desired effect.
|
||||
|
||||
.IP "\fBmfd\fR <\fIline\fR> <\fItext\fR>"
|
||||
Set the text on the MFD \fIline\fR. \fIline\fR can be 0, 1 or 2, and refers to
|
||||
the first, second or third line of the multi-function display respectively.
|
||||
\fItext\fR cannot have embedded NUL characters (0x00) and must correspond
|
||||
with the character map of the MFD. \fItext\fR should be quoted in order to
|
||||
preserve embedded whitespace. To pass raw hex values, use
|
||||
.BR printf (1)
|
||||
as shown in the examples section. Note that \fItext\fR is limited to a length
|
||||
of 16 characters. While you can pass longer strings, they will be truncated.
|
||||
|
||||
.IP "\fBled\fR <\fIled-id\fR> <\fIstate\fR>"
|
||||
Set the LED \fIled-id\fR to \fIstate\fR.
|
||||
|
||||
.IP "\fBblink\fR {\fBon\fR | \fBoff\fR}"
|
||||
Turn the \fBblink\fR state \fBon\fR or \fBoff\fR.
|
||||
|
||||
.IP "\fBshift\fR {\fBon\fR | \fBoff\fR}"
|
||||
Turn the \fBshift\fR indicator in the multi-function display \fBon\fR or
|
||||
\fBoff\fR.
|
||||
|
||||
.IP "\fBclock\fR {\fBlocal\fR | \fBgmt\fR} {\fB12hr\fR | \fB24hr\fR} {\fBddmmyy\fR | \fBmmddyy\fR | \fByymmdd\fR}"
|
||||
Set the clock 1 display to the current time and date in either the \fBlocal\fR
|
||||
timezone, or in \fBgmt\fR timezone. Clock can be configured to display in either
|
||||
\fB12hr\fB or \fB24hr\fR mode. Date can be displayed in one of the following
|
||||
formats: \fBddmmyy\fR, \fBmmddyy\fR, or \fByymmdd\fR.
|
||||
|
||||
.IP "\fBoffset\fR" {\fB2\fR | \fB3\fR} <\fIoffset-val\fR> {\fB12hr\fR | \fB24hr\fB}"
|
||||
Set the offsets for clocks \fB2\fR or \fB3\fR and configure them in \fB12hr\fR
|
||||
or \fB24hr\fR modes. \fIoffset-val\fR is in minutes from clock 1 and can range
|
||||
from -1440 to +1440.
|
||||
|
||||
.IP "\fBraw\fR <\fIwIndex\fR> <\fIwValue\fR>"
|
||||
Send a raw vendor control request to the X52 Pro.
|
||||
|
||||
\fBWARNING:\fR You should only use this if you know what you are doing. Sending
|
||||
an invalid control sequence can potentially destroy your device.
|
||||
|
||||
.SH LEDs
|
||||
|
||||
.SS "LED IDs"
|
||||
This is the list of LEDs supported by the X52 Pro.
|
||||
|
||||
.IP \[bu]
|
||||
fire
|
||||
.IP \[bu]
|
||||
a
|
||||
.IP \[bu]
|
||||
b
|
||||
.IP \[bu]
|
||||
d
|
||||
.IP \[bu]
|
||||
e
|
||||
.IP \[bu]
|
||||
t1
|
||||
.IP \[bu]
|
||||
t2
|
||||
.IP \[bu]
|
||||
t3
|
||||
.IP \[bu]
|
||||
pov
|
||||
.IP \[bu]
|
||||
clutch
|
||||
.IP \[bu]
|
||||
throttle
|
||||
|
||||
.SS "LED States"
|
||||
This is the list of LED states supported by the X52 Pro.
|
||||
|
||||
.IP \[bu]
|
||||
off
|
||||
.IP \[bu]
|
||||
on
|
||||
.IP \[bu]
|
||||
red
|
||||
.IP \[bu]
|
||||
amber
|
||||
.IP \[bu]
|
||||
green
|
||||
|
||||
.P
|
||||
Note that the \fBon\fR state is only supported by the \fBfire\fR and
|
||||
\fBthrottle\fR LEDs, and they do not support the \fBred\fR, \fBamber\fR
|
||||
and \fBgreen\fR states. The remaining LEDs do not support the \fBon\fR
|
||||
state, but support all the other states.
|
||||
|
||||
.SH KNOWN ISSUES
|
||||
|
||||
.BR x52cli
|
||||
does not maintain any state between invocations. As a result, the
|
||||
\fBclock\fR command will reset the offsets for clocks 2 and 3 back to 0
|
||||
in 12hr mode.
|
||||
|
||||
.SH PERMISSIONS
|
||||
|
||||
You must have write permissions to the USB device in order to use the
|
||||
\fBlibx52\fR library, and by extension
|
||||
.BR x52cli
|
||||
|
||||
The simplest method is to run
|
||||
.BR x52cli
|
||||
as root, preferably through
|
||||
.BR sudo (8)
|
||||
|
||||
.SH EXAMPLES
|
||||
|
||||
.PD 0
|
||||
\fBx52cli\fR led t1 off
|
||||
.P
|
||||
Turn off the T1 LED.
|
||||
|
||||
\fBx52cli\fR led B amber
|
||||
.P
|
||||
Turn the B LED to Amber
|
||||
|
||||
\fBx52cli\fR mfd 0 "Hello World"
|
||||
.P
|
||||
Set line 1 of the MFD to display "Hello World"
|
||||
|
||||
\fBx52cli\fR mfd 1 "$(printf '\\x9FC\\xE2mo Est\\xE0s?')"
|
||||
.P
|
||||
Set line 2 of the MFD to display "¿Cómo Estás?"
|
||||
|
||||
Loading…
Reference in New Issue