Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Tedd Ho-Jeong An <hj.tedd.an@gmail.com>
To:     linux-bluetooth@vger.kernel.org
Subject: [BlueZ PATCH v3 2/4] monitor: Convert manpage to rst format
Date:   Mon,  3 May 2021 22:02:05 -0700
Message-Id: <20210504050207.841261-3-hj.tedd.an@gmail.com>
In-Reply-To: <20210504050207.841261-1-hj.tedd.an@gmail.com>
References: <20210504050207.841261-1-hj.tedd.an@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

From: Tedd Ho-Jeong An <tedd.an@intel.com>

This patch adds support to convert reStructuredText formatted btmon
manpage to manpage with rst2man tool.
---
 Makefile.am       |  15 +++-
 Makefile.tools    |   4 +-
 configure.ac      |   4 ++
 doc/btmon.txt     |  35 ----------
 monitor/btmon.rst | 171 ++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 189 insertions(+), 40 deletions(-)
 delete mode 100644 doc/btmon.txt
 create mode 100644 monitor/btmon.rst

diff --git a/Makefile.am b/Makefile.am
index cb0d5fc0a..4e9cae885 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -594,7 +594,7 @@ if LIBRARY
 pkgconfig_DATA = lib/bluez.pc
 endif
 
-EXTRA_DIST += $(manual_pages:.1=.txt)
+EXTRA_DIST += $(manual_pages:.1=.rst)
 
 DISTCHECK_CONFIGURE_FLAGS = --disable-datafiles --enable-library \
 						--enable-health \
@@ -616,11 +616,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 160272212..a39e3e334 100644
--- a/Makefile.tools
+++ b/Makefile.tools
@@ -51,10 +51,10 @@ monitor_btmon_LDADD = lib/libbluetooth-internal.la \
 				src/libshared-mainloop.la $(UDEV_LIBS) -ldl
 
 if MANPAGES
-man_MANS += doc/btmon.1
+man_MANS += monitor/btmon.1
 endif
 endif
-manual_pages += doc/btmon.1
+manual_pages += monitor/btmon.1
 
 if LOGGER
 pkglibexec_PROGRAMS += tools/btmon-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..c59fdde62
--- /dev/null
+++ b/monitor/btmon.rst
@@ -0,0 +1,171 @@
+=====
+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.26.3