Hi Luiz,
On Thu, 2021-04-29 at 20:51 -0700, Luiz Augusto von Dentz wrote:
> 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.
I converted all manpages in the tree to .rst and ready to submit.
Can I combine all in this series or wait for this to merge first?
> > 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
> >
>
>
