Hi Tedd,
On Tue, Apr 27, 2021 at 11:24 PM Tedd Ho-Jeong An <hj.tedd.an@xxxxxxxxx> wrote:
>
> From: Tedd Ho-Jeong An <tedd.an@xxxxxxxxx>
>
> This patch updates the manpage for btmon written in rst format.
> ---
> Makefile.am | 26 ++++---
> Makefile.tools | 4 ++
> configure.ac | 4 ++
> doc/btmon.txt | 35 ----------
> monitor/btmon.rst | 172 ++++++++++++++++++++++++++++++++++++++++++++++
I do wonder why you change the location from doc to monitor, I think
we actually should keep all the documentation under doc and perhaps
even have a dedicated make target for those since we would likely want
to generate all the manpages from rst which may be time consuming so
people not interested on it can just skip it.
> 5 files changed, 197 insertions(+), 44 deletions(-)
> delete mode 100644 doc/btmon.txt
> create mode 100644 monitor/btmon.rst
>
> diff --git a/Makefile.am b/Makefile.am
> index f98243f72..759110cbd 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -60,6 +60,11 @@ else
> build_plugindir = $(plugindir)
> endif
>
> +if MANPAGES
> +man_MANS =
> +endif
> +
> +manual_pages = monitor/btmon.1
>
> plugin_LTLIBRARIES =
>
> @@ -579,13 +584,7 @@ if LIBRARY
> pkgconfig_DATA = lib/bluez.pc
> endif
>
> -manual_pages = doc/btmon.1
> -
> -if MANPAGES
> -dist_noinst_MANS += $(manual_pages)
> -endif
> -
> -EXTRA_DIST += $(manual_pages:.1=.txt)
> +EXTRA_DIST += $(manual_pages:.1=.rst)
>
> DISTCHECK_CONFIGURE_FLAGS = --disable-datafiles --enable-library \
> --enable-health \
> @@ -607,11 +606,20 @@ SED_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
> $(SED) -e 's,@pkglibexecdir\@,$(pkglibexecdir),g' \
> < $< > $@
>
> +if RUN_RST2MAN
> +RST2MAN_PROCESS = $(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
> + $(RST2MAN) --strict --no-raw \
> + --no-generator --no-datestamp $< $@
> +else
> +RST2MAN_PROCESS = $(AM_V_GEN)test -f $@ || \
> + { echo "Generated manual page $@ does not exist"; false; }
> +endif
> +
> %.service: %.service.in Makefile
> $(SED_PROCESS)
>
> -%.1: %.txt
> - $(AM_V_GEN)a2x --doctype manpage --format manpage $(srcdir)/$<
> +%.1: %.rst Makefile
> + $(RST2MAN_PROCESS)
>
> src/builtin.h: src/genbuiltin $(builtin_sources)
> $(AM_V_GEN)$(srcdir)/src/genbuiltin $(builtin_modules) > $@
> diff --git a/Makefile.tools b/Makefile.tools
> index 57e858290..9b452aa74 100644
> --- a/Makefile.tools
> +++ b/Makefile.tools
> @@ -49,6 +49,10 @@ monitor_btmon_SOURCES = monitor/main.c monitor/bt.h \
> monitor/tty.h
> monitor_btmon_LDADD = lib/libbluetooth-internal.la \
> src/libshared-mainloop.la $(UDEV_LIBS) -ldl
> +
> +if MANPAGES
> +man_MANS += monitor/btmon.1
> +endif
> endif
>
> if LOGGER
> diff --git a/configure.ac b/configure.ac
> index dbd98c9ad..d7e4766e4 100644
> --- a/configure.ac
> +++ b/configure.ac
> @@ -326,7 +326,11 @@ AM_CONDITIONAL(DATAFILES, test "${enable_datafiles}" != "no")
> AC_ARG_ENABLE(manpages, AC_HELP_STRING([--enable-manpages],
> [enable building of manual pages]),
> [enable_manpages=${enableval}])
> +if (test "${enable_manpages}" != "no"); then
> + AC_CHECK_PROGS(RST2MAN, [rst2man rst2man.py], "no")
> +fi
> AM_CONDITIONAL(MANPAGES, test "${enable_manpages}" = "yes")
> +AM_CONDITIONAL(RUN_RST2MAN, test "${enable_manpages}" = "yes" && test "${RST2MAN}" != "no")
>
> AC_ARG_ENABLE(testing, AC_HELP_STRING([--enable-testing],
> [enable testing tools]),
> diff --git a/doc/btmon.txt b/doc/btmon.txt
> deleted file mode 100644
> index 7a7fc537b..000000000
> --- a/doc/btmon.txt
> +++ /dev/null
> @@ -1,35 +0,0 @@
> -BTMON(1)
> -========
> -:doctype: manpage
> -
> -
> -NAME
> -----
> -btmon - Bluetooth monitor
> -
> -
> -SYNOPSIS
> ---------
> -*btmon* ['OPTIONS']
> -
> -
> -DESCRIPTION
> ------------
> -The btmon(1) command provides access to the Bluetooth subsystem monitor
> -infrastructure for reading HCI traces.
> -
> -
> -AUTHOR
> -------
> -btmon was originally written by Marcel Holtmann.
> -
> -
> -RESOURCES
> ----------
> -See <http://www.bluez.org/>
> -
> -
> -COPYING
> --------
> -Free use of this software is granted under ther terms of the GNU Lesser
> -General Public Licenses (LGPL).
> diff --git a/monitor/btmon.rst b/monitor/btmon.rst
> new file mode 100644
> index 000000000..29d275eb3
> --- /dev/null
> +++ b/monitor/btmon.rst
> @@ -0,0 +1,172 @@
> +=====
> +btmon
> +=====
> +
> +-----------------
> +Bluetooth monitor
> +-----------------
> +
> +:Authors: - Marcel Holtmann <marcel@xxxxxxxxxxxx>
> + - Tedd Ho-Jeong An <tedd.an@xxxxxxxxx>
> +:Copyright: Free use of this software is granted under ther terms of the GNU
> + Lesser General Public Licenses (LGPL).
> +:Version: BlueZ
> +:Date: April 2021
> +:Manual section: 1
> +:Manual group: Linux System Administration
> +
> +SYNOPSYS
> +========
> +
> +**btmon** [*OPTIONS* ...]
> +
> +DESCRIPTION
> +===========
> +
> +The btmon(1) command provides access to the Bluetooth subsystem monitor
> +infrastructure for reading HCI traces.
> +
> +OPTIONS
> +=======
> +
> +-r FILE, --read FILE Read traces in btsnoop format from *FILE*.
> +-w FILE, --write FILE Save traces in btsnoop format to *FILE*.
> +-a FILE, --analyze FILE Analyze traces in btsnoop format from *FILE*.
> + It displays the devices found in the *FILE* with
> + its packets by type.
> +-s SOCKET, --server SOCKET Start monitor server socket.
> +-p PRIORITY, --priority PRIORITY Show only priority or lower for user log.
> +
> +.. list-table::
> + :header-rows: 1
> + :widths: auto
> + :stub-columns: 1
> +
> + * - *PRIORITY*
> + - NAME
> +
> + * - **3**
> + - Error
> +
> + * - **4**
> + - Warning
> +
> + * - **6**
> + - Information (Default)
> +
> + * - **7**
> + - Debug. **debug** can be used.
> +
> +-i NUM, --index NUM Show only specified controller. *hciNUM* is also
> + acceptable. This is useful to capture the traces
> + from the specific controller when the multiple
> + controllers are presented.
> +
> +-d TTY, --tty TTY Read data from *TTY*.
> +
> +-B SPEED, --rate SPEED Set TTY speed. The default *SPEED* is 115300
> +
> +-V COMPID, --vendor COMPID Set the default company identifier. The *COMPID* is
> + a unique number assigned by the Bluetooth SIG to
> + a member company and can be found/searched from the
> + Bluetooth SIG webpage.
> +
> + For example, Intel is 2 and Realtek is 93.
> +
> +-M, --mgmt Open channel for mgmt events.
> +
> +-t, --time Show a time instead of time offset.
> +
> +-T, --date Show a time and date information instead of
> + time offset.
> +
> +-S, --sco Dump SCO traffic in raw hex format.
> +
> +-A, --a2dp Dump A2DP stream traffic in a raw hex format.
> +
> +-E IP, --ellisys IP Send Ellisys HCI Injection.
> +
> +-P, --no-pager Disable pager usage while reading the log file.
> +
> +-J OPTIONS, --jlink OPTIONS Read data from RTT. Each options are comma(,)
> + seprated without spaces.
> +
> +.. list-table::
> + :header-rows: 1
> + :widths: auto
> + :stub-columns: 1
> +
> + * - *OPTIONS*
> + - Description
> +
> + * - **DEVICE**
> + - Required. Set the target device.
> +
> + * - **SERIALNO**
> + - (Optional) Set the USB serial number. Default is **0**.
> +
> + * - **INTERFACE**
> + - (Optional) Target interface. Default is **swd**.
> +
> + * - **SPEED**
> + - (Optional) Set target interface speed in kHz. Default is **1000**.
> +
> +-R OPTIONS, --rtt OPTIONS RTT control block parameters. Each options are
> + comma(,) seprated without spaces.
> +
> +.. list-table::
> + :header-rows: 1
> + :widths: auto
> + :stub-columns: 1
> +
> + * - *OPTIONS*
> + - Description
> +
> + * - **ADDRESS**
> + - (Optional) Address of RTT buffer. Default is **0x00**
> +
> + * - **AREA**
> + - (Optional) Size of range to search in RTT buffer. Default is **0**
> +
> + * - **NAME**
> + - (Optional) Buffer name. Default is **btmonitor**
> +
> +-C WIDTH, --columns WIDTH Output width if not a terminal
> +
> +-c MODE, --color MODE Set output color. The possible *MODE* values are:
> + **auto|always|never**.
> +
> + Default value is **auto**
> +
> +-v, --version Show version
> +
> +-h, --help Show help options
> +
> +EXAMPLES
> +========
> +
> +Capture the traces from hci0 to hcidump.log file
> +------------------------------------------------
> +
> +.. code-block:: bash
> +
> + $ btmon -i hci0 -w hcidump.log
> +
> +Open the trace file
> +-------------------
> +
> +.. code-block:: bash
> +
> + $ btmon -r hcidump.log
> +
> +
> +RESOURCES
> +=========
> +
> +http://www.bluez.org
> +
> +REPORTING BUGS
> +==============
> +
> +linux-bluetooth@xxxxxxxxxxxxxxx
> +
> --
> 2.25.1
>
--
Luiz Augusto von Dentz
