Minor README changes

README.md

@@ -1,4 +1,4 @@
-# vaportrail
+# Vaportrail
 
 Vaportrail is a tool for data transmission over FM, using
 [RPITX](https://github.com/F5OEO/RPITX) to transmit from an out-of-the-box
@@ -8,18 +8,45 @@ Rudimentary block-based error correction is implemented using the
 transmits at 2000 bits per second using a bandwidth of roughly 31 KHz, and can
 likely work at higher data rates.
 
-
-## Building and Installing Vaportrail
-
-### Install RPITX On Transmitter
+<!-- TOC depthFrom:2 -->
+
+- [1. Building and Installing Vaportrail](#1-building-and-installing-vaportrail)
+  - [1.1. Install RPITX On Transmitter](#11-install-rpitx-on-transmitter)
+  - [1.2. Install GQRX And socat On Receiver](#12-install-gqrx-and-socat-on-receiver)
+    - [1.2.1. Mac](#121-mac)
+    - [1.2.2. Ubuntu](#122-ubuntu)
+    - [1.2.3. Arch Linux](#123-arch-linux)
+    - [1.2.4. Everything Else](#124-everything-else)
+  - [1.3. Vaportrail Binaries](#13-vaportrail-binaries)
+  - [1.4. Building From Source](#14-building-from-source)
+    - [1.4.1. Building on Raspberry Pi](#141-building-on-raspberry-pi)
+- [2. Using Vaportrail](#2-using-vaportrail)
+  - [2.1. Transmitting From a Raspberry Pi with `tools/transmit.sh`](#21-transmitting-from-a-raspberry-pi-with-toolstransmitsh)
+  - [2.2. Receiving With GQRX and `tools/receive.sh`](#22-receiving-with-gqrx-and-toolsreceivesh)
+  - [2.3. Using Vaportrail Directly](#23-using-vaportrail-directly)
+    - [2.3.1. Encode PCM Data](#231-encode-pcm-data)
+    - [2.3.2. Encode RPITX RF Commands](#232-encode-rpitx-rf-commands)
+    - [2.3.3. Decode PCM Data](#233-decode-pcm-data)
+- [3. Current Limitations](#3-current-limitations)
+  - [3.1. GQRX Can't Be Used Programmatically](#31-gqrx-cant-be-used-programmatically)
+  - [3.2. No Raspberry Pi Zero Support](#32-no-raspberry-pi-zero-support)
+  - [3.3. No Streaming Decoder](#33-no-streaming-decoder)
+  - [3.4. Issues With Streaming Encoding](#34-issues-with-streaming-encoding)
+
+<!-- /TOC -->
+
+<!-- This TOC is updated using the Markdown TOC package in VSCode -->
+
+## 1. Building and Installing Vaportrail
+
+### 1.1. Install RPITX On Transmitter
 
 Install RPITX from
 [https://github.com/F5OEO/rpitx](https://github.com/F5OEO/rpitx). Ensure the
 `rpitx` command is available in your PATH. RPITX's `install.sh` script will do
 this automatically by installing to /usr/bin
 
-
-### Install GQRX And socat On Receiver
+### 1.2. Install GQRX And socat On Receiver
 
 The current supported method of FM demodulation is to use GQRX, sending the
 output to a netcat or socat listener over UDP. This is a little janky, and
@@ -29,7 +56,7 @@ need to install the `gqrx` tool before using Vaportrail.
 The upside is, using GQRX makes it much easier to identify and isolate the
 signal before receiving due to its graphical interface.
 
-#### Mac
+#### 1.2.1. Mac
 
 Install socat with Homebrew
 
@@ -41,31 +68,32 @@ Alternatively, install with Homebrew
 
     brew cask install gqrx
 
-#### Ubuntu
+#### 1.2.2. Ubuntu
 
     apt-get install socat gqrx-sdr
 
-#### Arch Linux
+#### 1.2.3. Arch Linux
 
     pacman -S socat gqrx
 
-#### Everything Else
+#### 1.2.4. Everything Else
 
-See http://gqrx.dk/ for information on downloading and installing GQRX.
+See [http://gqrx.dk/](http://gqrx.dk/) for information on downloading and
+installing GQRX.
 
 Consult your distribution's package repositories for socat installation.
 
 
-### Vaportrail Binaries
+### 1.3. Vaportrail Binaries
 
 Compiling the libraries needed for Vaportrail can take quite a long time on a
 Raspberry Pi, so for your convenience we've included a [binary ARMv7 build in
 the Releases]().
 
-### Building From Source
+### 1.4. Building From Source
 
-First, install the stack build tool. See https://www.haskellstack.org/ for
-details.
+First, install the stack build tool. See
+[https://www.haskellstack.org/](https://www.haskellstack.org/) for details.
 
 Then, from the project root folder:
 
@@ -80,9 +108,9 @@ You may either copy the file from that folder to wherever you want, or run
 
     stack install
 
-to automatically install the executable in $HOME/.local/bin    
+to automatically install the executable in `$HOME/.local/bin`
 
-#### Building on Raspberry Pi
+#### 1.4.1. Building on Raspberry Pi
 
 Compiling Haskell can take a good chunk of RAM. When building on a Raspberry Pi
 it's a good idea to force stack to use only a single build job. By default,
@@ -100,9 +128,9 @@ dependencies as well. Our initial build took a little over two hours.
 Re-compiling after changing the source code is significantly faster, in the
 order of one to two minutes.
 
-## Using Vaportrail
+## 2. Using Vaportrail
 
-### Transmitting From a Raspberry Pi with `tools/transmit.sh`
+### 2.1. Transmitting From a Raspberry Pi with `tools/transmit.sh`
 
 Ensure the `vaportrail` and `rpitx` binaries are both available on your PATH
 (meaning you can run them without a folder prefix such as `./`).  If you
@@ -111,15 +139,16 @@ installed `vaportrail` with `stack install`, add the following line to your
 
     export PATH="$HOME/.local/bin:$PATH"
 
-Then, simply pipe data into `tools/transmit.sh`. For example, to transmit the text "Hello":
+Then, simply pipe data into `tools/transmit.sh`. For example, to transmit the
+text "Hello":
 
     echo "Hello" | tools/transmit.sh
 
 To transmit a file named `transmit_me`:
 
     tools/transmit.sh < transmit_me
 
-### Receiving With GQRX and `tools/receive.sh`
+### 2.2. Receiving With GQRX and `tools/receive.sh`
 
 Open GQRX and tune to the frequency on which you're going to transmit.
 
@@ -158,12 +187,12 @@ Once the transmission has completed, press enter to decode it.
 If all data was received successfully, you should see the same data you
 transmitted.
 
-### Using Vaportrail Directly
+### 2.3. Using Vaportrail Directly
 
 This section documents how to use the `vaportrail` command directly, for if you
 want to skip the wrapper scripts and do it yourself.
 
-#### Encode PCM Data
+#### 2.3.1. Encode PCM Data
 
     vaportrail enc_pcm
 
@@ -175,7 +204,7 @@ fail for infinite data sources such as `tail -f`.
 
     vaportrail enc_pcm | vaportrail dec
 
-#### Encode RPITX RF Commands
+#### 2.3.2. Encode RPITX RF Commands
 
     vaportrail enc
 
@@ -190,20 +219,20 @@ here:
 
     4 byte padding                      Unused padding data
 
-#### Decode PCM Data
+#### 2.3.3. Decode PCM Data
 
     vaportrail dec
 
 Read a raw PCM audio stream and decode a Vaportrail-encoded signal. The input
 stream must consist of a single 48000Hz channel of 16-bit signed little-endian
 samples.
 
-## Current Limitations
+## 3. Current Limitations
 
 There's a few limitations in Vaportrail which are definitely solvable, but have
 not been fixed yet. These are listed below.
 
-### GQRX Can't Be Used Programmatically
+### 3.1. GQRX Can't Be Used Programmatically
 
 I (unknownln) have never interfaced with the RTL-SDR programmatically, so I
 have no idea how to do it yet. Since Vaportrail currently relies on the
@@ -217,7 +246,7 @@ place of GQRX. That said, `rtl_fm`'s FM demodulation isn't as good as GQRX's,
 so Vaportrail may not be able to decode the output. If I test this method and
 get it working I'll update this README with details.
 
-### No Raspberry Pi Zero Support
+### 3.2. No Raspberry Pi Zero Support
 
 As of writing this README, Vaportrail can only encode data on a Raspberry Pi 2
 or Raspberry Pi 3. An encoder will have to be written in another language to
@@ -230,16 +259,14 @@ ones and zeroes in the data. We'll need to write our own implementation of an
 RNG to ensure that the encoder and decoder get the same results from the same
 input seed.
 
-
-### No Streaming Decoder
+### 3.3. No Streaming Decoder
 
 Additionally, Vaportrail can not yet decode a stream of data, meaning a
 received transmission must be written entirely to disk before it can be
 decoded. *Note by unknownln: I'm currently working on a solution to this, and I'll
 hopefully have it implemented within a week or two of today, August 02, 2017.*
 
-
-### Issues With Streaming Encoding
+### 3.4. Issues With Streaming Encoding
 
 There's been an issue when encoding data while piping to RPITX where RPITX will
 sometimes cut off before the transmission is finished. The cause is currently
@@ -248,5 +275,3 @@ for Pi Zero support, or the rewrite to fix the streaming decoder. However, it
 is something that should remain on the radar moving forward. To work around it,
 the transmission script currently encodes input data fully to a temp file
 before transmitting that file.
-
-