Hi Tedd,
On Fri, Apr 30, 2021 at 2:43 PM Tedd Ho-Jeong An <hj.tedd.an@xxxxxxxxx> wrote:
>
> 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?
Have you added a make target for those? I really don't mind having the
manpages generated within the same location of the binary, although I
think it would be more organized to have it in one place, but a make
target would probably be a good practice.
> > > 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
