| Message ID | 20210428062214.335567-1-hj.tedd.an@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | [BlueZ,v2] monitor: Update manpage | expand |
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
Hi Luiz, >> 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. in iwd, we moved all the manual pages next to the source of the daemon/tools. So yes, I would put this into monitor directory as well. Regards Marcel
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@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. 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@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 > > > >
Hi Tedd, On Fri, Apr 30, 2021 at 2:43 PM Tedd Ho-Jeong An <hj.tedd.an@gmail.com> 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@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. > > 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@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
Hi Luiz, >>>> 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. >> >> 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. the way how this works is that in a git tree they are always generated unless disabled or rst2man is not available. And in a tarball, the generated manual pages are shipped, which means they are not needed to be generated. So no specific make target required. Lets just copy what iwd repository doing since that is working fine. Regards Marcel
Hi Marcel, On Sat, 2021-05-01 at 03:59 +0200, Marcel Holtmann wrote: > Hi Luiz, > > > > > > 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. > > > > > > 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. > > the way how this works is that in a git tree they are always generated unless disabled or rst2man is not available. And in a tarball, the generated manual pages are shipped, which means they are not > needed to be generated. So no specific make target required. Lets just copy what iwd repository doing since that is working fine. > To align with iwd way, I suggest to make some changes in Makefile as well. For example, disabling manpages are not working because the manpages are added to dist_man_MANS without checking MANPAGES flags. I converted all existing manpages to .rst format and ready to submit. I will add them in this patch set. > Regards > > Marcel > Regards, Tedd
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 +
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 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 197 insertions(+), 44 deletions(-) delete mode 100644 doc/btmon.txt create mode 100644 monitor/btmon.rst