Re: [BlueZ v2] monitor: Update manpage

[Luiz Augusto von Dentz <luiz.dentz@gmail.com>]

Hi Tedd,

On Tue, Apr 27, 2021 at 11:24 PM Tedd Ho-Jeong An <hj.tedd.an@gmail.com> wrote:
>
> From: Tedd Ho-Jeong An <tedd.an@intel.com>
>
> 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@holtmann.org>
> +          - Tedd Ho-Jeong An <tedd.an@intel.com>
> +: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@vger.kernel.org
> +
> --
> 2.25.1
>


-- 
Luiz Augusto von Dentz