Skip to content

Commit

Permalink
man: manage common parts of man pages in one place
Browse files Browse the repository at this point in the history 
and stitch them together at build time, rather than using copy/paste
everywhere, and forcing mutliple updates.

Update a tiny bit the man pages, to be a little more pedanitic about
serial ports, and a few other minor updates.

Signed-off-by: Robin Getz <rgetz@mathworks.com>
Signed-off-by: Paul Cercueil <paul@crapouillou.net>
  • Loading branch information
@rgetz @pcercuei
rgetz authored and pcercuei committed May 11, 2023
1 parent 800c394 commit 9f4949f
Show file tree
Hide file tree
Showing 10 changed files with 123 additions and 260 deletions.
14 changes: 12 additions & 2 deletions man/CMakeLists.txt
View file
@@ -1,3 +1,6 @@
# it doesn't make sense to create man pages on windows, so we don't really
# worry about that.

if (WITH_MAN)
find_program(BASH_EXECUTABLE bash)
find_program(DATE_EXECUTABLE date)
Expand Down Expand Up @@ -36,8 +39,15 @@ if (WITH_MAN)
if (WITH_TESTS)
list(APPEND MAN1 iio_attr.1 iio_info.1 iio_readdev.1 iio_reg.1 iio_writedev.1)
foreach(_page ${MAN1})
configure_file( ${CMAKE_CURRENT_SOURCE_DIR}/${_page}.in
${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_MANDIR}/${_page} @ONLY)
execute_process(
COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/make_util_pages.sh
${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/${_page}.1.in
OUTPUT_FILE ${CMAKE_CURRENT_BINARY_DIR}/${_page}.1.in
)
configure_file(
${CMAKE_CURRENT_BINARY_DIR}/${_page}.1.in
${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_MANDIR}/${_page}.1 @ONLY
)
endforeach()
if (WITH_DOC)
file(MAKE_DIRECTORY ${CMAKE_HTML_DEST_DIR}/man1)
Expand Down
62 changes: 4 additions & 58 deletions man/iio_attr.1.in
View file
Expand Up @@ -82,45 +82,11 @@ Read and Write IIO Context attributes
.TP
.B \-D \-\-debug-attr
Read and Write IIO Debug attributes
.TP
.B \-S, \-\-scan
Scan for available IIO contexts, optional arg of specific backend(s) 'ip', 'usb' or 'ip,usb'.
Specific options for USB include Vendor ID, Product ID to limit scanning to specific devices 'usb=0456:b673'.
vid,pid are hexadecimal numbers (no prefix needed), "*" (match any for pid only)
If no argument is given, it checks all that are availble.
.TP
.B \-h, \-\-help
Tells
.I iio_attr
to display some help, and then quit.

##COMMON_COMMANDS_START##
##COMMON_COMMANDS_STOP##
.SH OPTIONS
.TP
.B \-a, \-\-auto
Look around for devices (locally, ip, and usb), and if there is only one device
found, connect to it.
.TP
.B \-u, \-\-uri
The Uniform Resource Identifier
.I (uri)
for connecting to devices, can be one of:
.RS
.IP ip:[address]
network address, either numeric (192.168.0.1) or network hostname (pluto.local)
.IP ip:
blank, if compiled with zeroconf support, will find an IIO device on network
.IP usb:[device:port:instance]
normally returned from
.B iio_info -s
or
.B iio_attr -S
.IP usb:
blank, if there is only one IIO device plugged into USB, find it, and attach to it.
.IP serial:[port],[baud],[config]
serial configuration, serial:/dev/ttyUSB0,115200,8n1 115200 baud, 8 data bits, no partity, one stop bit
.IP local:
with no address part
.RE
##COMMON_OPTION_START##
##COMMON_OPTION_STOP##
.TP
.B \-i, \-\-input-channel
Filters channels by input channels only
Expand All @@ -140,23 +106,3 @@ Generate small C or python snippets that emulate what you are doing on the comma
.SH RETURN VALUE
If the specified device is not found, a non-zero exit code is returned.

.SH "SEE ALSO"
.ad l
.BR iio_attr (1),
.BR iio_info (1),
.BR iio_readdev (1),
.BR iio_reg (1),
.BR iio_writedev (1),
.BR libiio (3)
.PP
libiio home page:
.BR \%https://wiki.analog.com/resources/tools-software/linux-software/libiio
.PP
libiio code:
.BR \%https://github.com/analogdevicesinc/libiio
.PP
Doxygen for libiio
.BR \%https://analogdevicesinc.github.io/libiio/
.SH BUGS
All bugs are tracked at:
.BR \%https://github.com/analogdevicesinc/libiio/issues
11 changes: 11 additions & 0 deletions man/iio_common_cmds.1
View file
@@ -0,0 +1,11 @@
.TP
.B \-h, \-\-help
Tells
.I ##APP_NAME##
to display some help, and then quit.
.TP
.B \-S, \-\-scan [backends]
Scan for available IIO contexts, optional arg of specific backend(s) 'ip', 'usb' or 'ip:usb'.
Specific options for USB include Vendor ID, Product ID to limit scanning to specific devices 'usb=0456,b673'.
vid,pid are hexadecimal numbers (no prefix needed), "*" (match any for pid only)
If no argument is given, it checks all that are availble.
20 changes: 20 additions & 0 deletions man/iio_common_footer.1
View file
@@ -0,0 +1,20 @@
.SH "SEE ALSO"
.ad l
.BR iio_attr (1),
.BR iio_info (1),
.BR iio_readdev (1),
.BR iio_reg (1),
.BR iio_writedev (1),
.BR libiio (3)
.PP
libiio home page:
.BR \%https://wiki.analog.com/resources/tools-software/linux-software/libiio
.PP
libiio code:
.BR \%https://github.com/analogdevicesinc/libiio
.PP
Doxygen for libiio
.BR \%https://analogdevicesinc.github.io/libiio/
.SH BUGS
All bugs are tracked at:
.BR \%https://github.com/analogdevicesinc/libiio/issues
36 changes: 36 additions & 0 deletions man/iio_common_opts.1
View file
@@ -0,0 +1,36 @@
.TP
.B \-u, \-\-uri
The Uniform Resource Identifier
.I (uri)
for connecting to devices, can be one of:
.RS
.IP ip:[address]
network address, either numeric (192.168.0.1) or network hostname
.IP ip:
blank, if compiled with zeroconf support, will find an IIO device on network
.IP usb:[device:port:instance]
normally returned from
.B ##APP_NAME## -S
.IP serial:[port],[baud],[settings]
which are controlled, and need to match the iiod (or tinyiiod) on the other end of the serial port.
.RS
.IP [port]
is something like '/dev/ttyUSB0' on Linux, and 'COM4' on Windows.
.IP [baud]
is is normally one of 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200 [default], 128000 or 256000, but can vary system to system.
.IP [settings]
would normally be configured as '8n1' this is controlled by:
.RS
.IP data_bits:
(5, 6, 7, 8 [default], or 9)
.IP parity_bits:
('n' none [default], 'o' odd, 'e' even, 'm' mark, or 's' space)
.IP stop_bits:
(1 [default, or 2)
.IP flow_control:
('0' none [default], 'x' Xon Xoff, 'r' RTSCTS, or 'd' DTRDSR)
.RE
.RE
.IP local:
with no address part.
.RE
70 changes: 4 additions & 66 deletions man/iio_info.1.in
View file
Expand Up @@ -31,82 +31,20 @@ iio_info \- list IIO devices and device attributes
[
.I options
]
-x <xml_file>
.br
.B iio_info
[
.I options
]
-n <hostname>
.br
.B iio_info
[
.I options
]
-u <uri>
.SH DESCRIPTION
.B iio_info
is a utility for displaying information about local or remote IIO devices

.SH OPTIONS
.TP
.B \-h, \-\-help
Tells
.I iio_info
to display some help, and then quit.
.TP
.B \-x, \-\-xml
Use the XML backend with the provided XML file
.TP
.B \-n, \-\-network
Use the network backend with the provided hostname
.TP
.B \-u, \-\-uri
The Uniform Resource Identifier
.I (uri)
for connecting to devices, can be one of:
.RS
.IP ip:[address]
network address, either numeric (192.168.0.1) or network hostname
.IP ip:
blank, if compiled with zeroconf support, will find an IIO device on network
.IP usb:[device:port:instance]
normally returned from
.B iio_info -s
.IP serial:[port]
.IP local
with no address part
.RE
.TP
.B \-S, \-\-scan
Scan for available IIO contexts, optional arg of specific backend(s) 'ip', 'usb' or 'ip,usb'.
Specific options for USB include Vendor ID, Product ID to limit scanning to specific devices 'usb=0456:b673'.
vid,pid are hexadecimal numbers (no prefix needed), "*" (match any for pid only)
If no argument is given, it checks all that are availble.
##COMMON_COMMANDS_START##
##COMMON_COMMANDS_STOP##
##COMMON_OPTION_START##
##COMMON_OPTION_STOP##
.TP
.B \-a, \-\-auto
Scan for available contexts and if only one is available use it.

.SH RETURN VALUE
If the specified device is not found, a non-zero exit code is returned.

.SH "SEE ALSO"
.ad l
.BR iio_attr (1),
.BR iio_info (1),
.BR iio_readdev (1),
.BR iio_reg (1),
.BR iio_writedev (1),
.BR libiio (3)
.PP
libiio home page:
.BR \%https://wiki.analog.com/resources/tools-software/linux-software/libiio
.PP
libiio code:
.BR \%https://github.com/analogdevicesinc/libiio
.PP
Doxygen for libiio
.BR \%https://analogdevicesinc.github.io/libiio/
.SH BUGS
All bugs are tracked at:
.BR \%https://github.com/analogdevicesinc/libiio/issues
57 changes: 4 additions & 53 deletions man/iio_readdev.1.in
View file
Expand Up @@ -37,30 +37,8 @@ iio_readdev \- read buffers from an IIO device
is a utility for reading buffers from connected IIO devices, and sending resutls to standard out.

.SH OPTIONS
.TP
.B \-h, \-\-help
Tells
.I iio_readdev
to display some help, and then quit.
.B \-n, \-\-network
Use the network backend with the provided hostname
.TP
.B \-u, \-\-uri
The Uniform Resource Identifier
.I (uri)
for connecting to devices, can be one of:
.RS
.IP ip:[address]
network address, either numeric (192.168.0.1) or network hostname
.IP ip:
blank, if compiled with zeroconf support, will find an IIO device on network
.IP usb:[device:port:instance]
normally returned from
.B iio_info -s
.IP serial:[port]
.IP local
with no address part
.RE
##COMMON_COMMANDS_START##
##COMMON_COMMANDS_STOP##
.TP
.B \-t \-\-trigger
Use the specified trigger, if needed on the specified channel
Expand All @@ -73,15 +51,8 @@ Number of samples (not bytes) to capture, 0 = infinite. Default is 0.
.TP
.B \-T \-\-timeout
Buffer timeout in milliseconds. 0 = no timeout. Default is 0.
.TP
.B \-a, \-\-auto
Scan for available contexts and if only one is available use it.
.TP
.B \-S, \-\-scan
Scan for available IIO contexts, optional arg of specific backend(s) 'ip', 'usb' or 'ip,usb'.
Specific options for USB include Vendor ID, Product ID to limit scanning to specific devices 'usb=0456:b673'.
vid,pid are hexadecimal numbers (no prefix needed), "*" (match any for pid only)
If no argument is given, it checks all that are availble.
##COMMON_OPTION_START##
##COMMON_OPTION_STOP##
.SH RETURN VALUE
If the specified device is not found, a non-zero exit code is returned.

Expand Down Expand Up @@ -115,23 +86,3 @@ And plots the data with gnuplot.
.B \f(WCgnuplot \-e \(dq\&set term png; set output 'sample.png'; plot 'sample.dat' binary format='%short%short' using 1 with lines, 'sample.dat' binary format='%short%short' using 2 with lines;\(dq\&\fP
.RE

.SH "SEE ALSO"
.ad l
.BR iio_attr (1),
.BR iio_info (1),
.BR iio_readdev (1),
.BR iio_reg (1),
.BR iio_writedev (1),
.BR libiio (3)
.PP
libiio home page:
.BR \%https://wiki.analog.com/resources/tools-software/linux-software/libiio
.PP
libiio code:
.BR \%https://github.com/analogdevicesinc/libiio
.PP
Doxygen for libiio
.BR \%https://analogdevicesinc.github.io/libiio/
.SH BUGS
All bugs are tracked at:
.BR \%https://github.com/analogdevicesinc/libiio/issues
32 changes: 5 additions & 27 deletions man/iio_reg.1.in
View file
Expand Up @@ -34,41 +34,19 @@ iio_reg \- do a low level read or write to SPI or I2C register
<device> <register> [<value>]
.SH DESCRIPTION
.B iio_reg
is a utility for debugging local IIO devices.
is a utility for debugging local or remote IIO devices.
It should not be used by normal users, and is normally used by driver
developers during development, or by end users debugging a driver, or sending
in a feature request.
It provides a mechanism to read or write SPI or I2C registers for IIO devices.
This can be useful when troubleshooting IIO devices, and understanding how
the Linux IIO subsystem is managing the device.

This IIO utility does not work across a network or USB context.
.SH OPTIONS
.TP
.B \-h, \-\-help
Tells
.I iio_reg
to display some help, and then quit.
##COMMON_COMMANDS_START##
##COMMON_COMMANDS_STOP##
##COMMON_OPTION_START##
##COMMON_OPTION_STOP##
.SH RETURN VALUE
If the specified device is not found, a non-zero exit code is returned.

.SH "SEE ALSO"
.ad l
.BR iio_attr (1),
.BR iio_info (1),
.BR iio_readdev (1),
.BR iio_reg (1),
.BR iio_writedev (1),
.BR libiio (3)
.PP
libiio home page:
.BR \%https://wiki.analog.com/resources/tools-software/linux-software/libiio
.PP
libiio code:
.BR \%https://github.com/analogdevicesinc/libiio
.PP
Doxygen for libiio
.BR \%https://analogdevicesinc.github.io/libiio/
.SH BUGS
All bugs are tracked at:
.BR \%https://github.com/analogdevicesinc/libiio/issues

0 comments on commit 9f4949f

Please sign in to comment.