Man pages and install channels.yaml as example

8 files changed, 137 insertions, 1 deletions

diff --git a/debian/changelog b/debian/changelog
index a3bf174..822e85f 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -3,7 +3,12 @@ gr-dab (0.3-2) UNRELEASED; urgency=medium
   * debian/control:
     - Depend on matching version of libgnuradio-dab3.7.13
     - Set Multi-Arch: same for gr-dab-dev
+    - Build-depend on txt2man
+  * debian/gr-dab.examples: Install channels.yaml
   * debian/gr-dab.install: Install sdr-zmq-daemon
+  * debian/rules:
+    - New overrides for building man page with txt2man
+  * debiaen/man: Man pages generated via txt2man
 
  -- Ruben Undheim <ruben.undheim@gmail.com>  Fri, 02 Nov 2018 19:01:29 +0100
 
diff --git a/debian/control b/debian/control
index 1391ff6..506b4e4 100644
--- a/debian/control
+++ b/debian/control
@@ -9,7 +9,8 @@ Build-Depends: debhelper (>= 11),
                doxygen,
                pkg-config,
                python-gtk2,
-               swig
+               swig,
+               txt2man
 Standards-Version: 4.2.1
 Vcs-Browser: https://salsa.debian.org/rubund/gr-dab
 Vcs-Git: https://salsa.debian.org/rubund/gr-dab.git
diff --git a/debian/gr-dab.examples b/debian/gr-dab.examples
index e39721e..eaa2dd4 100644
--- a/debian/gr-dab.examples
+++ b/debian/gr-dab.examples
@@ -1 +1,2 @@
 examples/*
+docs/channels.yaml
diff --git a/debian/gr-dab.manpages b/debian/gr-dab.manpages
new file mode 100644
index 0000000..068ecf5
--- /dev/null
+++ b/debian/gr-dab.manpages
@@ -0,0 +1,2 @@
+debian/man/grdab.1
+debian/man/sdr-zmq-daemon.1
diff --git a/debian/man/genmanpages.sh b/debian/man/genmanpages.sh
new file mode 100755
index 0000000..c0274a0
--- /dev/null
+++ b/debian/man/genmanpages.sh
@@ -0,0 +1,5 @@
+#!/bin/bash
+
+
+txt2man -d "${CHANGELOG_DATE}" -t GRDAB                  -s 1 grdab.txt               > grdab.1
+txt2man -d "${CHANGELOG_DATE}" -t SDR-ZMQ-DAEMON         -s 1 sdr-zmq-daemon.txt      > sdr-zmq-daemon.1
diff --git a/debian/man/grdab.txt b/debian/man/grdab.txt
new file mode 100644
index 0000000..bb3151a
--- /dev/null
+++ b/debian/man/grdab.txt
@@ -0,0 +1,88 @@
+NAME
+  grdab - DAB / DAB+ receiver for software defined radio
+
+SYNOPSIS
+  grdab [global_options] <command> [options]
+
+DESCRIPTION
+
+  All SDRs supported by gr-osmosdr and which can tune to the DAB frequencies can be used with grdab. It has been verified to work with RTL-SDR, HackRF and USRP B200. grdab can receive both DAB and DAB+ audio.
+
+  Calibration:  
+
+  When connecting a new radio, run:
+
+    grdab adjust
+
+  This will bring up a GUI where you will see the frequency spectrum and the constellation diagram.
+
+    1. Drag the channel selector to a valid DAB/DAB+ frequency in your area.
+    2. Adjust the gain sliders such that frequency spectrum looks good. It should be an almost square looking wide signal.
+    3. Adjust the ppm slider until the constellation diagram consists of 4 quite confined dots.
+    4. Then click 'save configuration'
+    5. Your SDR is now calibrated and can be used to receive DAB/DAB+ audio.
+
+  The calibration data is stored in the file ~/.grdab/adjustment.yaml. Whenever connecting a new SDR, you will have to repeat the adjustment procedure above.
+
+  Check available channels:  
+
+  To see what channels are available on a chosen frequency, run:
+
+    grdab info -f <frequency_in_mhz>
+
+  Listen to DAB/DAB+:   
+
+  When you find a channel, you can start receiving audio with:
+
+    grdab receive -f 227.360 --bit_rate 80 --address 204 --subch_size 60 --protect_level 2 --audiorate 48000
+
+  where you replace the different options with the output from 'grdab info' for the desired channel. You might have to experiment with a few different values for '--audiorate' (such as 44100 or 48000). Note that DAB+ is default. To receive classic DAB, add '--classic' an argument.
+
+  Ncurses app:  
+
+  If you create a file called ~/.grdab/channels.yaml, and list all the channels in your area,
+  you can afterward use the grdab ncurses application:
+
+    grdab curses
+
+  It allows you to select a channel and listen to it. See /usr/share/doc/gr-dab/examples/channels.yaml for an example of a channels.yaml file
+
+  ZMQ source:  
+
+  To allow starting and stopping grdab without having to reinitialize the Software Defined Radio, you can start apps/sdr-zmq-daemon in the background. If you then start grdab with `grdab -z`, it will start much faster.
+
+OPTIONS
+
+  Commands:
+
+    grdab [global_options] adjust [options]   - Adjustment GUI for gain, timing error etc.
+    grdab [global_options] info [options]     - List DAB/DAB+ channels on a specific frequency
+    grdab [global_options] receive [options]  - Receive audio from a DAB/DAB+ channel
+    grdab [global_options] curses [options]   - Ncurses GUI for selecting between multiple channels
+
+
+  Global options:  
+    -z                          ZeroMQ mode. Expects zmq-sdr-daemon to be running
+    --server <address>          Address to ZeroMQ (Default is: tcp://127.0.0.1:10444)
+    --server_control <address>  Address to ZeroMQ for configuration (Default is: tcp://127.0.0.1:10445)
+
+  Other options (common for all):  
+    -f/--freq <freq>          Receive frequency in MHz
+
+  Other options (for 'grdab receive' only):  
+    -a/--audiorate <rate>     Audio rate in Hz (default: 48000)
+    --bit_rate <val>          Bit rate of the DAB/DAB+ channel.
+    --address <val>           Address of the DAB/DAB+ channel.
+    --subch_size <val>        Subchannel size of the DAB/DAB+ channel.
+    --protect_level <val>     Protection level of the DAB/DAB+ channel.
+    --classic                 Use DAB instead of DAB+
+ 
+SEE ALSO
+  sdr-zmq-daemon(1)
+
+
+AUTHOR
+  This manual page was written by Ruben Undheim <rubund@debian.org> for the Debian project (and may be used by others).
+
+
+
diff --git a/debian/man/sdr-zmq-daemon.txt b/debian/man/sdr-zmq-daemon.txt
new file mode 100644
index 0000000..30bfd57
--- /dev/null
+++ b/debian/man/sdr-zmq-daemon.txt
@@ -0,0 +1,26 @@
+NAME
+  sdr-zmq-daemon - ZeroMQ daemon for Software Defined Radios (SDRs)
+
+SYNOPSIS
+  sdr-zmq-daemon
+
+DESCRIPTION
+
+  Simply start with no options. It will connect to your software defined radio, and start providing IQ data over ZeroMQ on address tcp://127.0.0.1:10444 and provide a configuration interface on tcp://127.0.0.1:10445.
+  It is intended to be used together with grdab (Using the 'grdab -z' option).
+
+  All SDRs supported by gr-osmosdr can be used with sdr-zmq-daemon. It has been verified to work with RTL-SDR, HackRF and USRP B200.
+
+OPTIONS
+
+  No options available
+ 
+SEE ALSO
+  grdab(1)
+
+
+AUTHOR
+  This manual page was written by Ruben Undheim <rubund@debian.org> for the Debian project (and may be used by others).
+
+
+
diff --git a/debian/rules b/debian/rules
index 9104296..10dde04 100755
--- a/debian/rules
+++ b/debian/rules
@@ -21,6 +21,10 @@ override_dh_auto_test:
 	#dh_auto_test
 
 
+override_dh_clean:
+	dh_clean
+	$(RM) debian/man/*.1
+
 # We do not want to install the development files in this package
 override_dh_auto_install:
 	dh_auto_install
@@ -28,3 +32,7 @@ override_dh_auto_install:
 	$(RM) debian/tmp/usr/lib/python2.7/dist-packages/grdab/*.pyo
 	$(RM) debian/tmp/usr/lib/python2.7/dist-packages/grdab/app/*.pyc
 	$(RM) debian/tmp/usr/lib/python2.7/dist-packages/grdab/app/*.pyo
+
+override_dh_installman:
+	cd debian/man ; CHANGELOG_DATE="$(CHANGELOG_DATE)" ./genmanpages.sh
+	dh_installman