about summary refs log tree commit homepage
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/.gitignore1
-rw-r--r--Documentation/GNUmakefile29
-rw-r--r--Documentation/dtas-archive.pod74
-rw-r--r--Documentation/dtas-archive.txt62
-rw-r--r--Documentation/dtas-console.pod94
-rw-r--r--Documentation/dtas-console.txt73
-rw-r--r--Documentation/dtas-ctl.pod (renamed from Documentation/dtas-ctl.txt)40
-rw-r--r--Documentation/dtas-cueedit.pod38
-rw-r--r--Documentation/dtas-cueedit.txt36
-rw-r--r--Documentation/dtas-enq.pod43
-rw-r--r--Documentation/dtas-enq.txt41
-rw-r--r--Documentation/dtas-env.pod75
-rw-r--r--Documentation/dtas-env.txt60
-rw-r--r--Documentation/dtas-msinkctl.pod (renamed from Documentation/dtas-msinkctl.txt)32
-rw-r--r--Documentation/dtas-player.pod (renamed from Documentation/dtas-player.txt)67
-rw-r--r--Documentation/dtas-player_effects.pod103
-rw-r--r--Documentation/dtas-player_effects.txt57
-rw-r--r--Documentation/dtas-player_protocol.pod454
-rw-r--r--Documentation/dtas-player_protocol.txt326
-rw-r--r--Documentation/dtas-player_sink_examples.pod (renamed from Documentation/dtas-player_sink_examples.txt)46
-rw-r--r--Documentation/dtas-sinkedit.pod (renamed from Documentation/dtas-sinkedit.txt)58
-rw-r--r--Documentation/dtas-sourceedit.pod (renamed from Documentation/dtas-sourceedit.txt)59
-rw-r--r--Documentation/dtas-splitfx.pod271
-rw-r--r--Documentation/dtas-splitfx.txt188
-rw-r--r--Documentation/dtas-tl.pod122
-rw-r--r--Documentation/dtas-tl.txt96
-rw-r--r--Documentation/dtas-xdelay.pod96
-rw-r--r--Documentation/dtas-xdelay.txt76
-rwxr-xr-xDocumentation/update-footer.rb24
29 files changed, 1575 insertions, 1166 deletions
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index fc2662e..99e2662 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -3,3 +3,4 @@
 *.1
 *.5
 *.7
+*.txt
diff --git a/Documentation/GNUmakefile b/Documentation/GNUmakefile
index 88df59e..783cc82 100644
--- a/Documentation/GNUmakefile
+++ b/Documentation/GNUmakefile
@@ -3,12 +3,18 @@
 all::
 
 INSTALL = install
-PANDOC = pandoc
-PANDOC_OPTS = -f markdown --email-obfuscation=none
-pandoc = $(PANDOC) $(PANDOC_OPTS)
+POD2MAN = pod2man
+-include ../GIT-VERSION-FILE
+release := dtas $(VERSION)
+POD2MAN_OPTS = -v -r '$(release)' --stderr -d 1994-10-02 -c 'dtas user manual'
+pod2man = $(POD2MAN) $(POD2MAN_OPTS)
+POD2TEXT = pod2text
+POD2TEXT_OPTS = --stderr
+pod2text = $(POD2TEXT) $(POD2TEXT_OPTS)
 
 m1 =
 m1 += dtas-console
+m1 += dtas-cueedit
 m1 += dtas-ctl
 m1 += dtas-enq
 m1 += dtas-msinkctl
@@ -23,6 +29,7 @@ m1 += dtas-archive
 m7 =
 m7 += dtas-player_protocol
 m7 += dtas-player_sink_examples
+m7 += dtas-player_effects
 m7 += dtas-env
 
 man1 := $(addsuffix .1, $(m1))
@@ -47,8 +54,20 @@ install-man: man
         $(INSTALL) -d -m 755 $(DESTDIR)$(man7dir)
         $(INSTALL) -m 644 $(man1) $(DESTDIR)$(man1dir)
         $(INSTALL) -m 644 $(man7) $(DESTDIR)$(man7dir)
-%.1 %.7 : %.txt
-        $(pandoc) -s -t man < $< > $@
+
+%.1 : %.pod
+        $(pod2man) -s 1 $< $@+ && mv $@+ $@
+
+%.7 : %.pod
+        $(pod2man) -s 7 $< $@+ && mv $@+ $@
+
+all :: $(mantxt)
+
+mantxt = $(addsuffix .txt, $(m1) $(m7))
+
+%.txt : %.pod
+        $(pod2text) $< $@+ && mv $@+ $@
 
 clean::
         $(RM) $(man1) $(man7)
+        $(RM) $(addsuffix .txt.gz, $(m1) $(m7))
diff --git a/Documentation/dtas-archive.pod b/Documentation/dtas-archive.pod
new file mode 100644
index 0000000..38f5570
--- /dev/null
+++ b/Documentation/dtas-archive.pod
@@ -0,0 +1,74 @@
+% dtas-archive(1) dtas user manual
+
+=head1 NAME
+
+dtas-archive - paranoid audio file copy
+
+=head1 SYNOPSYS
+
+dtas-archive [OPTIONS] SOURCE DESTINATION
+
+=head1 DESCRIPTION
+
+dtas-archive is intended for archiving audio data to/from laptops,
+marginal USB ports, and computers without ECC memory, attempting
+to read data multiple times in an attempt to detect memory or
+bus corruption.  dtas-archive may only be effective on machines
+running the Linux kernel where L<posix_fadvise(2)> can be used to
+drop caches for a particular file after L<fsync(2)>.
+
+dtas-archive spawns L<sox(1)> to archive audio data (likely uncompressed
+WAVE) to FLAC and verifies the result using L<sndfile-cmp(1)>, a tool
+implemented by different than sox and less likely to share the same bugs
+(if any) as sox.
+
+=head1 OPTIONS
+
+=over
+
+=item -j, --jobs [JOBS]
+
+Number of jobs to run in parallel.  Incrementing this may hurt
+performance on slow storage devices.  Default: 1
+
+=item -n, --dry-run
+
+Print, but do not run the commands to be executed
+
+=item -s, --quiet, --silent
+
+Silent operation, commands are not printed as executed
+
+=item -S, --stats
+
+Run and save the text output of the sox "stats" effect as
+$DESTINATION_FILE_WITHOUT_SUFFIX.stats next to the output file
+
+=item -k, --keep-going
+
+Continue after error
+
+=item -r, --repeat [COUNT]
+
+Number of times to repeat the L<sndfile-cmp(1)> check.  Default: 1
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 SEE ALSO
+
+L<sndfile-cmp(1)>, L<sox(1)>
diff --git a/Documentation/dtas-archive.txt b/Documentation/dtas-archive.txt
deleted file mode 100644
index fdc818d..0000000
--- a/Documentation/dtas-archive.txt
+++ /dev/null
@@ -1,62 +0,0 @@
-% dtas-archive(1) dtas user manual
-%
-
-# NAME
-
-dtas-archive - paranoid audio file copy
-
-# SYNOPSYS
-
-dtas-archive [OPTIONS] SOURCE DESTINATION
-
-# DESCRIPTION
-
-dtas-archive is intended for archiving audio data to/from laptops,
-marginal USB ports, and computers without ECC memory, attempting
-to read data multiple times in an attempt to detect memory or
-bus corruption.  dtas-archive may only be effective on machines
-running the Linux kernel where posix_fadvise(2) can be used to
-drop caches for a particular file after fsync(2).
-
-dtas-archive spawns sox(1) to archive audio data (likely uncompressed
-WAVE) to FLAC and verifies the result using sndfile-cmp(1), a tool
-implemented by different than sox and less likely to share the same bugs
-(if any) as sox.
-
-# OPTIONS
-
--j, \--jobs [JOBS]
-:    Number of jobs to run in parallel.  Incrementing this may hurt
-     performance on slow storage devices.  Default: 1
-
--n, \--dry-run
-:    Print, but do not run the commands to be executed
-
--s, \--quiet, \--silent
-:    Silent operation, commands are not printed as executed
-
--S, \--stats
-:    Run and save the text output of the sox "stats" effect as
-     $DESTINATION_FILE_WITHOUT_SUFFIX.stats next to the output file
-
--k, \--keep-going
-:    Continue after error
-
--r, \--repeat [COUNT]
-:    Number of times to repeat the sndfile-cmp(1) check.  Default: 1
-
-# COPYRIGHT
-
-Copyright 2015-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# SEE ALSO
-
-sndfile-cmp(1), sox(1)
diff --git a/Documentation/dtas-console.pod b/Documentation/dtas-console.pod
new file mode 100644
index 0000000..e7b980c
--- /dev/null
+++ b/Documentation/dtas-console.pod
@@ -0,0 +1,94 @@
+% L<dtas-console(1)> dtas user manual
+
+=head1 NAME
+
+dtas-console - rudimentary curses console client for dtas-player
+
+=head1 SYNOPSIS
+
+dtas-console
+
+=head1 DESCRIPTION
+
+dtas-console displays the elapsed decoder time of the track, which can be
+used as an approximation of the current playback time of a track.
+
+It cannot display an accurate playback time due to variable buffering
+in the sinks and pipes.
+
+See L<dtas-player_protocol(7)> for a detailed description of the protocol.
+
+=head1 KEYBOARD CONTROL
+
+Key bindings are inspired partially by L<mplayer(1)>
+
+=over
+
+=item 'j'/'k' - seek backward/forward 5 seconds
+
+=item LEFT/RIGHT - seek backward/forward 10 seconds
+
+=item UP/DOWN - seek forward/backward 1 minute
+
+=item PGUP/PGDWN - seek forward/backward 10 minutes
+
+=item SPACE - toggle play/pause state of the playback
+
+=item 'p'/'P' - decrease/increase timer resolution
+
+=item BACKSPACE - seek to the beginning of the track
+
+=item 7/8 - decrease/increase ReplayGain preamp
+
+=item 9/0 - decrease/increase software volume
+
+=item '=' - set software volume to 1.0 (no adjustment)
+
+=item 'm' - mute set software volume to 0.0 (mute)
+
+=item 'f'/'F' - decrease/increase ReplayGain fallback_gain value
+
+=item 'r'/'R' - cycle forward/backwards through ReplayGain modes
+
+=item 'q'/Ctrl-C - exit dtas-console
+
+=item 'o' - toggle display between HH:MM:SS and absolute seconds
+
+=back
+
+=head1 ENVIRONMENT
+
+DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
+This defaults to ~/.dtas/player.sock
+
+=head1 CAVEATS
+
+Increasing timer resolution increases the number of CPU wakeups and
+power consumption.   This defeats the efforts of dtas-player
+configurations which use large buffers (especially in the sink) to
+reduce wakeups and power consumption.
+
+In rare cases (or poorly-configured systems), increased wakeups from
+dtas-console will also increase contention with the sound card,
+negatively affecting audio quality even if CPU utilization is not
+a problem.
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-ctl(1)>,
+L<dtas-sinkedit(1)>, L<dtas-sourceedit(1)>
diff --git a/Documentation/dtas-console.txt b/Documentation/dtas-console.txt
deleted file mode 100644
index 7468ba6..0000000
--- a/Documentation/dtas-console.txt
+++ /dev/null
@@ -1,73 +0,0 @@
-% dtas-console(1) dtas user manual
-
-# NAME
-
-dtas-console - rudimentary curses console client for dtas-player
-
-# SYNOPSIS
-
-dtas-console
-
-# DESCRIPTION
-
-dtas-console displays the elapsed decoder time of the track, which can be
-used as an approximation of the current playback time of a track.
-
-It cannot display an accurate playback time due to variable buffering
-in the sinks and pipes.
-
-See dtas-player_protocol(7) for a detailed description of the protocol.
-
-# KEYBOARD CONTROL
-
-Key bindings are inspired partially by mplayer(1)
-
-- 'j'/'k' - seek backward/forward 5 seconds
-- LEFT/RIGHT - seek backward/forward 10 seconds
-- UP/DOWN - seek forward/backward 1 minute
-- PGUP/PGDWN - seek forward/backward 10 minutes
-- SPACE - toggle play/pause state of the playback
-- 'p'/'P' - decrease/increase timer resolution
-- BACKSPACE - seek to the beginning of the track
-- 7/8 - decrease/increase ReplayGain preamp
-- 9/0 - decrease/increase software volume
-- '=' - set software volume to 1.0 (no adjustment)
-- 'm' - mute set software volume to 0.0 (mute)
-- 'f'/'F' - decrease/increase ReplayGain fallback_gain value
-- 'r'/'R' - cycle forward/backwards through ReplayGain modes
-- 'q'/Ctrl-C - exit dtas-console
-- 'o' - toggle display between HH:MM:SS and absolute seconds
-
-# ENVIRONMENT
-
-DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
-This defaults to ~/.dtas/player.sock
-
-# CAVEATS
-
-Increasing timer resolution increases the number of CPU wakeups and
-power consumption.   This defeats the efforts of dtas-player
-configurations which use large buffers (especially in the sink) to
-reduce wakeups and power consumption.
-
-In rare cases (or poorly-configured systems), increased wakeups from
-dtas-console will also increase contention with the sound card,
-negatively affecting audio quality even if CPU utilization is not
-a problem.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-dtas-player(1), dtas-player_protocol(7), dtas-ctl(1), dtas-sinkedit(1),
-dtas-sourceedit(1)
diff --git a/Documentation/dtas-ctl.txt b/Documentation/dtas-ctl.pod
index b2cf20b..771f6b2 100644
--- a/Documentation/dtas-ctl.txt
+++ b/Documentation/dtas-ctl.pod
@@ -1,29 +1,28 @@
 % dtas-ctl(1) dtas user manual
-%
 
-# NAME
+=head1 NAME
 
 dtas-ctl - low-level client for dtas-player
 
-# SYNOPSYS
+=head1 SYNOPSYS
 
 dtas-ctl [ARGS...]
 
-# DESCRIPTION
+=head1 DESCRIPTION
 
 dtas-ctl passes command-line arguments as-is to dtas-player.  It is mainly
 useful for simple commands such as ("current", "play_pause", "pause", "play",
 "rg RGARGS", "seek HH:MM:SS", "skip").
 
-See dtas-player_protocol(7) for a detailed description of the protocol.
+See L<dtas-player_protocol(7)> for a detailed description of the protocol.
 
-# EXAMPLES
+=head1 EXAMPLES
 
 display the currently playing track
 
         $ dtas-ctl current
 
-enqueue a file for playback (dtas-enq(1) is easier to use, here)
+enqueue a file for playback (L<dtas-enq(1)> is easier to use, here)
 
         $ dtas-ctl enq /absolute/path/to/file
 
@@ -49,28 +48,31 @@ skip to the next track
         $ dtas-ctl skip
 
 To play the output of an arbitrary command (note the quotes) and usage
-of $SOXFMT (see dtas-player_protocol(7)).
+of $SOXFMT (see L<dtas-player_protocol(7)>).
 
         $ dtas-ctl enq-cmd 'sox -n $SOXFMT - synth 3 pluck'
 
-# ENVIRONMENT
+=head1 ENVIRONMENT
 
 DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
 This defaults to ~/.dtas/player.sock
 
-# CONTACT
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
 
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
 No subscription is necessary to post to the mailing list.
 
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
 
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 
-# SEE ALSO
+=head1 SEE ALSO
 
-dtas-player(1), dtas-player_protocol(7), dtas-enq(1), dtas-sinkedit(1),
-dtas-sourceedit(1)
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-enq(1)>,
+L<dtas-sinkedit(1)>, L<dtas-sourceedit(1)>
diff --git a/Documentation/dtas-cueedit.pod b/Documentation/dtas-cueedit.pod
new file mode 100644
index 0000000..669374b
--- /dev/null
+++ b/Documentation/dtas-cueedit.pod
@@ -0,0 +1,38 @@
+% dtas-cueedit(1) dtas user manual
+
+=head1 NAME
+
+dtas-cueedit - edit embedded cuesheets in audio files
+
+=head1 SYNOPSYS
+
+dtas-cueedit /path/to/audio.flac
+
+=head1 DESCRIPTION
+
+dtas-cueedit spawns an editor to edit the embedded cuesheet in FLAC files.
+In the future, other audio formats with embedded cuesheets may be supported.
+Use with the L<metaflac(1)> is required.
+
+=head1 ENVIRONMENT
+
+VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<metaflac(1)>
diff --git a/Documentation/dtas-cueedit.txt b/Documentation/dtas-cueedit.txt
deleted file mode 100644
index 2fc0510..0000000
--- a/Documentation/dtas-cueedit.txt
+++ /dev/null
@@ -1,36 +0,0 @@
-% dtas-cueedit(1) dtas user manual
-%
-
-# NAME
-
-dtas-cueedit - edit embedded cuesheets in audio files
-
-# SYNOPSYS
-
-dtas-cueedit /path/to/audio.flac
-
-# DESCRIPTION
-
-dtas-cueedit spawns an editor to edit the embedded cuesheet in FLAC files.
-In the future, other audio formats with embedded cuesheets may be supported.
-Use with the metaflac(1) is required.
-
-# ENVIRONMENT
-
-VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-metaflac(1)
diff --git a/Documentation/dtas-enq.pod b/Documentation/dtas-enq.pod
new file mode 100644
index 0000000..2611a2e
--- /dev/null
+++ b/Documentation/dtas-enq.pod
@@ -0,0 +1,43 @@
+% dtas-enq(1) dtas user manual
+
+=head1 NAME
+
+dtas-enq - enqueue audio files for playback with dtas-player
+
+=head1 SYNOPSYS
+
+dtas-enq [FILE...]
+
+=head1 DESCRIPTION
+
+dtas-enq will enqueue a list of files given on the command-line to a
+running instance of L<dtas-player(1)>.  dtas-player will start playing
+the newly enqueued files in the order given.
+
+=head1 EXAMPLE
+
+        $ dtas-enq /path/to/your/favorite/album/*.flac
+
+=head1 ENVIRONMENT
+
+DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
+This defaults to ~/.dtas/player.sock
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<dtas-player(1)>, L<dtas-ctl(1)>
diff --git a/Documentation/dtas-enq.txt b/Documentation/dtas-enq.txt
deleted file mode 100644
index eecb62e..0000000
--- a/Documentation/dtas-enq.txt
+++ /dev/null
@@ -1,41 +0,0 @@
-% dtas-enq(1) dtas user manual
-%
-
-# NAME
-
-dtas-enq - enqueue audio files for playback with dtas-player
-
-# SYNOPSYS
-
-dtas-enq [FILE...]
-
-# DESCRIPTION
-
-dtas-enq will enqueue a list of files given on the command-line to a
-running instance of dtas-player(1).  dtas-player will start playing the
-newly enqueued files in the order given.
-
-# EXAMPLE
-
-        $ dtas-enq /path/to/your/favorite/album/*.flac
-
-# ENVIRONMENT
-
-DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
-This defaults to ~/.dtas/player.sock
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-dtas-player(1), dtas-ctl(1)
diff --git a/Documentation/dtas-env.pod b/Documentation/dtas-env.pod
new file mode 100644
index 0000000..b16da35
--- /dev/null
+++ b/Documentation/dtas-env.pod
@@ -0,0 +1,75 @@
+% dtas-env(7) dtas user manual
+
+=head1 NAME
+
+dtas-env - environment variables used through DTAS
+
+=head1 DESCRIPTION
+
+As dtas uses Bourne shell and exposes it to users, dtas should have
+a cohesive set of common environment variables across its audio
+production and playback environments.  This attempts to document
+them.  Most of these environments are set and managed by dtas
+itself, but users editing commands (e.g. via L<dtas-sourcedit(1)>
+should be aware of them.
+
+=head1 ENVIRONMENT
+
+=over
+
+=item ECAFMT
+
+A snippet of command-line switches for ecasound describing
+audio format parameters (such as word length, channels, sample rate),
+see L<dtas-player_protocol(7)> for more info. (e.g. "-fs32_le,2,44100")
+
+=item INFILE
+
+The primary input file for playback or processing. (e.g. "/path/to/ex.flac")
+
+=item RGFX
+
+The sox effect used for applying ReplayGain compensation.
+Only used during playback in dtas-player.  (e.g. "gain -6.0").
+Removing this prevents ReplayGain from working and may damage
+playback equipment with loudly mastered music.
+
+=item SOXFMT
+
+A snippet of command-line switches for sox describing
+audio format parameters (such as word length, channels, sample rate),
+see L<dtas-player_protocol(7)> for more info. (e.g. "-ts32 -c2 -r44100")
+
+=item TRIMFX
+
+The sox effect used for seeking during playback with dtas-player
+and track offsets for dtas-splitfx.  (e.g. "trim 36000s")
+
+Additionally, L<dtas-splitfx(1)> documents more environment variables
+which are not used elsewhere.
+
+=back
+
+=head1 ENVIRONMENT FOR OTHER EXECUTABLES
+
+By virtue of running other programs, dtas indirectly uses many
+commonly-accepted environment variables such as EDITOR / VISUAL for
+selecting a text editor, and SOX_OPTS, AUDIODEV, AUDIODRIVER for L<sox(1)>
+and L<play(1)> commands and LADSPA_PATH for anything using LADSPA plugins
+(including sox).  The TMPDIR environment variable controls where
+temporary files are placed for most programs.
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
diff --git a/Documentation/dtas-env.txt b/Documentation/dtas-env.txt
deleted file mode 100644
index 8cbbd0a..0000000
--- a/Documentation/dtas-env.txt
+++ /dev/null
@@ -1,60 +0,0 @@
-% dtas-env(7) dtas user manual
-%
-
-# NAME
-
-dtas-env - environment variables used through DTAS
-
-# DESCRIPTION
-
-As dtas uses Bourne shell and exposes it to users, dtas should have
-a cohesive set of common environment variables across its audio
-production and playback environments.  This attempts to document
-them.  Most of these environments are set and managed by dtas
-itself, but users editing commands (e.g. via dtas-sourcedit(1)
-should be aware of them.
-
-# ENVIRONMENT
-
-ECAFMT - an snippet of command-line switches for ecasound describing
-audio format parameters (such as word length, channels, sample rate),
-see dtas-player_protocol(7) for more info. (e.g. "-fs32_le,2,44100")
-
-INFILE - the primary input file for playback or processing.
-(e.g. "/path/to/ex.flac")
-
-RGFX - the sox effect used for applying ReplayGain compensation.
-Only used during playback in dtas-player.  (e.g. "gain -6.0").
-Removing this prevents ReplayGain from working and may damage
-playback equipment with loudly mastered music.
-
-SOXFMT - an snippet of command-line switches for sox describing
-audio format parameters (such as word length, channels, sample rate),
-see dtas-player_protocol(7) for more info. (e.g. "-ts32 -c2 -r44100")
-
-TRIMFX - the sox effect used for seeking during playback with dtas-player
-and track offsets for dtas-splitfx.  (e.g. "trim 36000s")
-
-Additionally, dtas-splitfx(1) documents more environment variables
-which are not used elsewhere.
-
-# ENVIRONMENT FOR OTHER EXECUTABLES
-
-By virtue of running other programs, dtas indirectly uses many
-commonly-accepted environment variables such as EDITOR / VISUAL for
-selecting a text editor, and SOX_OPTS, AUDIODEV, AUDIODRIVER for sox(1)
-and play(1) commands and LADSPA_PATH for anything using LADSPA plugins
-(including sox).  The TMPDIR environment variable controls where
-temporary files are placed for most programs.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2015-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
diff --git a/Documentation/dtas-msinkctl.txt b/Documentation/dtas-msinkctl.pod
index 01a43c5..b7116ac 100644
--- a/Documentation/dtas-msinkctl.txt
+++ b/Documentation/dtas-msinkctl.pod
@@ -1,19 +1,19 @@
 % dtas-msinkctl(1) dtas user manual
 
-# NAME
+=head1 NAME
 
 dtas-msinkctl - activate/deactivate multiple sinks at once
 
-# SYNOPSYS
+=head1 SYNOPSYS
 
 dtas-msinkctl COMMAND
 dtas-msinkctl COMMAND [SINKS...]
 
-# DESCRIPTION
+=head1 DESCRIPTION
 
 dtas-msinkctl is useful for activating/deactivating multiple sinks.
 
-# EXAMPLES
+=head1 EXAMPLES
 
 Display only active sinks (unlike "dtas-ctl sink ls", which shows all sinks)
 
@@ -35,23 +35,27 @@ Remove SINK3 from the active set
 
     dtas-msinkctl active-add SINK3
 
-# ENVIRONMENT
+=head1 ENVIRONMENT
 
 DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
 This defaults to ~/.dtas/player.sock
 
-# CONTACT
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
 
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
 No subscription is necessary to post to the mailing list.
 
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
 
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 
-# SEE ALSO
+=head1 SEE ALSO
 
-dtas-player(1), dtas-player_protocol(7), dtas-ctl(1), dtas-sinkedit(1)
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-ctl(1)>,
+L<dtas-sinkedit(1)>
diff --git a/Documentation/dtas-player.txt b/Documentation/dtas-player.pod
index c8a17df..a146868 100644
--- a/Documentation/dtas-player.txt
+++ b/Documentation/dtas-player.pod
@@ -1,15 +1,14 @@
 % dtas-player(1) dtas user manual
-%
 
-# NAME
+=head1 NAME
 
 dtas-player - playback process for dtas
 
-# SYNOPSYS
+=head1 SYNOPSYS
 
 dtas-player
 
-# DESCRIPTION
+=head1 DESCRIPTION
 
 dtas-player is intended as a music player, but implemented as Unix
 process and pipeline manager, so it may run arbitrary commands and route
@@ -17,21 +16,21 @@ data to just about any process.
 
 dtas-player is currently only queue-based, enqueued tracks are played
 only once.  It only runs in a foreground console, so usage with
-screen(1) or tmux(1) is recommended.
+L<screen(1)> or L<tmux(1)> is recommended.
 
-By default, dtas-player uses the sox(1) command to decode audio, and
-pipes the data to a play(1) process (also distributed with sox).  It may
+By default, dtas-player uses the L<sox(1)> command to decode audio, and
+pipes the data to a L<play(1)> process (also distributed with sox).  It may
 be configured to output to multiple/arbitrary processes, and may invoke
 arbitrary commands for outputting audio (or any other data).
 
-dtas-player is controlled by a Unix socket, see dtas-player_protocol(7)
+dtas-player is controlled by a Unix socket, see L<dtas-player_protocol(7)>
 for details.  Given the power of dtas-player to run arbitrary commands,
 this socket is created with restricted permissions and is only
 accessible by the user who invoked dtas-player.
 
 dtas-player maintains state across restarts with a state file.
 
-# EXAMPLE
+=head1 EXAMPLE
 
 Starting dtas-player is easy, it takes no arguments:
 
@@ -51,39 +50,37 @@ To see information about the currently playing track in YAML:
 As you should be able to see, a "default" sink is automatically
 created and playing the audio.
 
-# TROUBLESHOOTING
+=head1 TROUBLESHOOTING
 
+=head2 Audio playback does not start
 
-
-## Audio playback does not start
-
-The most common problem with dtas-player is the play(1) command
+The most common problem with dtas-player is the L<play(1)> command
 (distributed with SoX) not using the correct audio device/driver.
-Ensuring the play(1) command works with dtas-player is important.
-Consult SoX documentation and mailing lists for getting play(1) to work,
+Ensuring the L<play(1)> command works with dtas-player is important.
+Consult SoX documentation and mailing lists for getting L<play(1)> to work,
 first.
 
 Once you find the correct AUDIODEV/AUDIODRIVER environment variables,
-you may set them via dtas-ctl(1):
+you may set them via L<dtas-ctl(1)>:
 
 To play audio on my favorite USB DAC directly to ALSA, I use:
 
     $ dtas-ctl sink ed default env.AUDIODEV=hw:DAC env.AUDIODRIVER=alsa
 
-## Seeking/playing audio from large video containers (e.g. VOB) fails
+=head2 Seeking/playing audio from large video containers (e.g. VOB) fails
 
 This is a problem with large VOBs.  We recommend breaking up the
-VOB into smaller files or using avconv(1) or ffmpeg(1) to extract
+VOB into smaller files or using L<avconv(1)> or L<ffmpeg(1)> to extract
 the desired audio stream.
 
       avconv -analyzeduration 2G -probesize 2G \
         -i input.vob -vn -sn -c:a copy -map 0:$STREAM_NR output.ext
 
-# ADVANCED EXAMPLES
+=head1 ADVANCED EXAMPLES
 
-See dtas_player-sink_examples(7) for more sink examples.
+See L<dtas_player-sink_examples(7)> for more sink examples.
 
-# ENVIRONMENT
+=head1 ENVIRONMENT
 
 DTAS_PLAYER_SOCK - the path to the dtas-player listen socket.
 This defaults to ~/.dtas/player.sock
@@ -102,24 +99,28 @@ exist in the source file:
     * REPLAYGAIN_ALBUM_PEAK
     * REPLAYGAIN_TRACK_PEAK
 
-# FILES
+=head1 FILES
 
 ~/.dtas/player_state.yml is a human-readable YAML file used to preserve
 state across restarts of dtas-player.
 
-# CONTACT
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
 
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
 No subscription is necessary to post to the mailing list.
 
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
 
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 
-# SEE ALSO
+=head1 SEE ALSO
 
-dtas-player_protocol(7), dtas-ctl(1), dtas-enq(1), dtas-sourceedit(1),
-dtas-sinkedit(1), sox(1), play(1), avconv(1), ffmpeg(1), screen(1), tmux(1)
+L<dtas-player_protocol(7)>, L<dtas-ctl(1)>, L<dtas-enq(1)>,
+L<dtas-sourceedit(1)>, L<dtas-sinkedit(1)>, L<sox(1)>, L<play(1)>,
+L<avconv(1)>, L<ffmpeg(1)>, L<screen(1)>, L<tmux(1)>
diff --git a/Documentation/dtas-player_effects.pod b/Documentation/dtas-player_effects.pod
new file mode 100644
index 0000000..149834a
--- /dev/null
+++ b/Documentation/dtas-player_effects.pod
@@ -0,0 +1,103 @@
+% dtas-player_effects(7) dtas user manual
+
+=head1 NAME
+
+L<dtas-player(1)> effects overview
+
+=head1 DESCRIPTION
+
+Effects in dtas-player may be applied either at the source or the sink.
+They are applied in the order described.
+
+=over
+
+=item 1. source effects
+
+Source effects are effects which should be applied per-source and do not
+rely on inter-track information.
+
+Examples include:
+
+=over
+
+=item ReplayGain (simple gain changes)
+
+=item anything which does not change the length of the audio:
+
+gain, stereo, highpass, lowpass, loudness, bass, treble, equalizer, ...
+
+=back
+
+Modifying source effects should introduce no extra gaps in playback.
+Effects which modify the length of the audio is not recommended here,
+as seek functionality will be impaired.
+
+=item 2. sink effects
+
+Sink effects are any effects which:
+
+=over
+
+=item 1) should only be applied to a specific sink
+
+=item 2) effects which require inter-track information
+
+(multiband delays/compressors/expanders)
+
+=item 3) alter the length of the audio
+
+=back
+
+In a multi-zone audio system (where each zone has its own sink), sink
+effects may also customize the sound of a certain zone while not
+affecting others.
+
+Examples include:
+
+=over
+
+=item equalizer effects (highpass/bass/treble/equalizer)
+
+=item loudness
+
+=item delaying a certain channel or frequency range for time-alignment
+
+=item compressors/limiters
+
+=item reverb
+
+=item gain
+
+=item remix (for stereo image adjustments)
+
+=back
+
+Additionally, effects which are necessary due to the limitation of the
+playback hardware are applied at the sink:
+
+=over
+
+=item rate
+
+=item dither
+
+=item remix (static channel mappings)
+
+=back
+
+=back
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
diff --git a/Documentation/dtas-player_effects.txt b/Documentation/dtas-player_effects.txt
deleted file mode 100644
index 91e846c..0000000
--- a/Documentation/dtas-player_effects.txt
+++ /dev/null
@@ -1,57 +0,0 @@
-Effects in dtas-player may be applied either at the source or the sink.
-They are applied in the order described.
-
-1. source effects
-
-  Source effects are effects which should be applied per-source and do not
-  rely on inter-track information.
-
-  Examples include:
-  - ReplayGain (simple gain changes)
-  - anything which does not change the length of the audio:
-    gain, stereo, highpass, lowpass, loudness, bass, treble, equalizer, ...
-
-  Modifying source effects should introduce no extra gaps in playback.
-  Effects which modify the length of the audio is not recommended here,
-  as seek functionality will be impaired.
-
-2. sink effects
-
-  Sink effects are any effects which:
-
-  1) should only be applied to a specific sink
-  2) effects which require inter-track information
-     (multiband delays/compressors/expanders)
-  3) alter the length of the audio
-
-  In a multi-zone audio system (where each zone has its own sink), sink
-  effects may also customize the sound of a certain zone while not
-  affecting others.
-
-  Examples include:
-  - equalizer effects (highpass/bass/treble/equalizer)
-  - loudness
-  - delaying a certain channel or frequency range for time-alignment
-  - compressors/limiters
-  - reverb
-  - gain
-  - remix (for stereo image adjustments)
-
-  Additionally, effects which are necessary due to the limitation of the
-  playback hardware are applied at the sink:
-
-  - rate
-  - dither
-  - remix (static channel mappings)
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
diff --git a/Documentation/dtas-player_protocol.pod b/Documentation/dtas-player_protocol.pod
new file mode 100644
index 0000000..cb2d07a
--- /dev/null
+++ b/Documentation/dtas-player_protocol.pod
@@ -0,0 +1,454 @@
+% dtas-player_protocol(7) dtas user manual
+
+=head1 NAME
+
+dtas-player_protocol - protocol for controling dtas-player
+
+=head1 DESCRIPTION
+
+NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE
+
+I'm considering a heavy revamp of this protocol.  The "OK" responses for
+a lot of commands may not be necessary since this is Unix sockets and
+not TCP, and I may move away from a request-response model and towards
+an entirely listen/notification model.  I have little experience in
+non-TCP-based application protocols, so this is an area of
+experimentation for me.
+
+This must stay over Unix sockets because filesystem permissions are
+needed to enforce code execution permissions.  dtas-player is really a
+shell in disguise, after all.
+
+Protocol feedback greatly appreciated, email us at L<dtas-all@nongnu.org>
+
+This gives a specification of the dtas-player protocol over a local Unix
+SOCK_SEQPACKET socket.  The dtas-player protocol should NOT be
+considered stable at this point and compatibility will break.
+
+Inspiration is taken from MPRIS and MPRIS 2.0 specifications (e.g.
+play_pause, play, pause), and there will be a proxy in the future to
+support MPRIS/MPRIS 2.0 clients.
+
+The DTAS_PLAYER_SOCK is the standard environment determining the control
+socket for L<dtas-player(1)>.  This defaults to $HOME/.dtas/player.sock
+if unset.
+
+Most low-level commands may be issued using the L<dtas-ctl(1)> command.
+
+Higher-level commands such as L<dtas-console(1)>, L<dtas-sourceedit(1)>,
+L<dtas-sinkedit(1)>, and L<dtas-enq(1)> also implement this protocol.
+
+=head1 ARGUMENT TYPES
+
+=over
+
+=item BOOLEAN - must be "true" or "false"
+
+=item INTEGER - a signed integer in decimal notation (base 10)
+
+=item UNSIGNED - an unsigned integer in decimal or hex notation
+
+=item ENVNAME - must be a suitable environment variable (setenv(3))
+
+=item ENVVALUE - must be a suitable environment variable (setenv(3))
+
+=item COMMAND - command to run
+
+This may be quoted string passed to sh -c "".
+Variable/argument expansion will be performed by the shell
+
+=item SOURCENAME - "sox" or "av", more backends may be supported in the future
+
+=item TIMESTAMP - a time stamp formatted in HH:MM:SS.FRAC (for seeking)
+
+=item TRACKID - a unique unsigned integer in decimal (base-10)
+
+This represents a track in the tracklist
+
+=item FILENAME
+
+An expanded pathname relative to / is recommended since
+dtas-player and the client may run in different directories
+
+=back
+
+=head1 VARIABLE EXPANSION
+
+For source and sink "command" arguments, the $SOXFMT and $ECAFMT
+environment variables are exported automatically to source to ease
+integration with L<sox(1)> and L<ecasound(1)>.
+
+Both $SOXFMT and $ECAFMT are based on the configured "format" of
+the dtas-player (see below).
+
+For all machines, $SOXFMT defaults to: -ts32 -c2 -r44100
+For little-endian machines, $ECAFMT defaults to: -fs32_le,2,44100
+
+=head1 COMMANDS
+
+Commands here should be alphabetized according to `LC_ALL=C sort'
+
+=over
+
+=item cd - change the current working directory of the player
+
+=item clear - clear current queue (current track/command continues running)
+
+PENDING: this may be renamed to "queue clear" or "queue-clear"
+
+=item cue - display the index/offsets of the embedded cue sheet
+
+=item cue next - skip to the next cue sheet offset
+
+This may skip to the next track if there is
+no embedded cue sheet or if playing the last (embedded) track
+
+=item cue prev - skip to the previous cue sheet offset
+
+This may just seek to the beginning
+if there is no embedded cue sheet or if we are playing the first
+(embedded) track.
+
+=item cue goto INTEGER - go to the cue index denoted by INTEGER
+
+0 is first track as returned by "cue".
+Negative values of INTEGER allows selecting track relative to the last
+track (-1 is the last track, -2 is the penultimate, and so on).
+
+=item current - output information about the current track/command in YAML
+
+The structure of this is unstable and subject to change.
+
+=item enq FILENAME - enqueue the given FILENAME for playback
+
+An expanded (full) pathname relative to '/' is recommended, as
+dtas-player and the client may be in different directories.
+PENDING: this may be renamed to "queue add"
+
+=item enq-cmd "COMMAND" - run the following command for playback
+
+The COMMAND is expected to output audio in the audio format matching
+the current audio format of the player.  This may be a shell pipeline
+and include multiple commands.  The $SOXFMT and $ECAFMT variables are
+available here.
+PENDING: this may be renamed to "queue add-cmd"
+
+=item env ENVTOSET=ENVVALUE ENVTOSET2=ENVVALUE2
+
+Set environment variables.  This affects all future source/sink
+processes as well as helper commands dtas-player may spawn
+(e.g. L<soxi(1)>).  Environment variables set this way are currently not
+preserved across invocations of L<dtas-player(1)>, but may change in the
+future.
+
+=item env ENVTOUNSET1# ENVTOUNSET#
+
+Unset the given environment variable.
+PENDING: the '#' is ugly and inconsistent with the per-sink/source.
+env.
+
+=item format FORMATARGS - configure the format between source and sink
+
+Changing this will affect the $SOXFMT and $ECAFMT environments passed
+to source and sink commands.  Changing this implies a "restart"
+Changing rate to 48000 is probably useful if you plan on playing to some
+laptop sound cards.  In all cases where "bypass" is supported, it
+removes the guarantee of gapless playback as the audio device(s)
+will likely need to be restarted.
+
+=over
+
+=item channels=(UNSIGNED|bypass) - (default: 2 (stereo))
+
+number of channels to use internally.  sox will internally invoke the remix
+effect when decoding.  This supports the value "bypass" (without
+quotes) to avoid the automatic remix effect.  Using "bypass" mode
+removes the guarantee of gapless playback, as the audio device will
+likely need to be restarted, introducing an audible gap.
+
+=item endian=(big|little|swap) - (default: native)
+
+there is probably no
+point in changing this unless you output over a network sink to
+a machine of different endianess.
+
+=item bits=(UNSIGNED|bypass) - (default: implied from type)
+
+Sample precision (decoded).
+This may be pointless and removed in the future, since the sample
+precision is implied from type.  This supports the value of "bypass"
+to avoid dither/truncation in later stages.
+
+=item rate=(UNSIGNED|bypass) - (default: 44100) - sample rate of audio
+
+Typical values of rate are 44100, 48000, 88200, 96000.  Not all
+DSP effects are compatible with all sampling rates/channels.
+This supports the value of "bypass" as well to avoid introducing
+software resamplers into the playback chain.
+
+=item type=(s16|s24|s32|u16|u24|u32|f32|f64) - (default: s32)
+
+Change the raw PCM format.  s32 currently offers the best performance
+when only sox/play are used.  f32 may offer better performance if
+piping to/from non-sox applications (e.g. ecasound)
+
+=back
+
+=item pause - pause playback
+
+  Player pause state is preserved across dtas-player invocations.
+
+=item play - restart playback from pause
+
+Playback sinks will yield control of the audio playback device once no
+source is playing.
+
+=item play_pause - toggle the play/pause state
+
+This starts playback if paused, and pauses playback if playing.
+
+=item queue cat - dump the contents of the queue as YAML
+
+This may include arbitrary commands to be executed, filenames,
+and offsets for playback.  The format is not intended to be
+stable and subject to internal changes in dtas-player.
+
+=item restart - restarts all processes in the current pipeline
+
+Playback will be momentarily interrupted while this change occurs.  This is
+necessary if one of the commands (e.g. sox or ecasound) or loaded
+libraries (e.g. a LADSPA plugin) is upgraded.  Use "source restart"
+instead to only restart the source chain, leaving the sinks
+untouched.
+
+=item rg RGARGS - configure ReplayGain support
+
+All FLOAT values may be adjusted via '+=' or '-=' instead of simple
+assignment ('=').  If RGARGS is empty, the current rg state of
+non-default values will be dumped in YAML.
+
+=over
+
+=item fallback_gain=FLOAT (-6.0) - dB value
+
+Adjust the volume by this level (usually negative) for tracks
+missing ReplayGain tags.  This is useful when the queue contains
+a mix of tracks with and without ReplayGain tags.
+
+=item fallback_track=BOOLEAN (true)
+
+When in album_gain mode, fallback to track_gain if the
+REPLAYGAIN_ALBUM_GAIN metadata is missing.
+
+=item mode=(album_gain|track_gain|track_norm|album_norm|off)
+
+This controls the ReplayGain tag to use.  The *_norm options
+are used for peak normalization and not commonly found in other
+players.
+
+=item preamp=FLOAT (0) - dB value
+
+Adjust the album_gain or track_gain amount by this value (in dB).
+
+=item norm_level=FLOAT (1.0 == dBFS)
+
+Controls the level to normalize to when using album_norm or track_norm.
+
+=back
+
+=item seek [+-]TIMESTAMP - seek the current track to a specified time.
+
+This is passed directly as the first argument for the L<sox(1)> "trim"
+command.   See the L<sox(1)> manpage for details.
+Seeking to a relative time is also supported by prefixing the time
+with '+' or '-'
+
+=item skip - abort current track/command
+
+This is accomplished via closing the output pipe.
+Running the "clear" command before this will abort playback.
+
+=item sink ls - list names of current sinks
+
+=item sink cat SINKNAME - dump SINKNAME config in YAML
+
+=item sink rm SINKNAME - remove SINKNAME
+
+=item sink ed SINKNAME SINKARGS - create/edit SINKNAME
+
+This currently does not restart running (active) sinks.
+This will stop active sinks if active is set to false, and start
+active sinks if active is set to true.
+See dtas-sinkedit(1) for an example of using this.
+
+=over
+
+=item command=COMMAND - change the command-line used for playback
+
+=item active=BOOLEAN - whether or not the sink will be in use (default: false)
+
+=item env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the sink process
+
+=item env#ENVNAME - unset ENVNAME in the sink process (only)
+
+=item prio=INTEGER - priority of the sink, lower values run first
+
+=item nonblock=BOOLEAN - drop audio data to avoid holding back other sinks
+
+=item pipe_size=UNSIGNED - set the size of the pipe for the sink (Linux-only)
+
+=back
+
+=item source cat SOURCENAME - dump the current source command and env in YAML
+
+=item source ed SOURCENAME SOURCEARGS - edit the source parameters.
+
+This changes here will immediately restart the source process.
+See the code for dtas-sourceedit(1) for an example of using this.
+
+=over
+
+=item command=COMMAND - change the command-line used to decode audio
+
+=item env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the source process
+
+=item env#ENVNAME - unset ENVNAME in the source process (only)
+
+=item tryorder=INTEGER - lower values are tried first
+
+=back
+
+PENDING: tryorder here is wrong and may be removed or changed.
+We need to account for at least two variables input file:
+
+=over
+
+=item 1. input type (flac/opus/mp3/etc)
+
+=item 2. transport protocol (local FS/http/ftp/sftp/etc)
+
+=back
+
+=item source ls
+
+Dump the names of sources sorted by tryorder
+
+=item source restart
+
+Restart the current source command.
+This can be useful if the source file is changed during playback
+and the current player process is holding onto an unlinked inode.
+This is advantageous over a full "restart" as there is no audible
+gap on most systems.
+
+=item state dump [FILENAME]
+
+Immediately dump the state of the player.  If a FILENAME is specified,
+the state is written to that file.  Otherwise, the default state file
+(configured via DTAS_PLAYER_STATE environment variable, defaulting
+to ~/.dtas/player_state.yml) is written to.  This does not use
+L<fsync(2)>, users requiring fsync should L<open(2)> that file and
+L<fsync(2)> it themselves if necessary.
+
+=item tl add FILENAME [TRACKID [BOOLEAN]]
+
+Add files to the tracklist with one arg, adds FILENAME to the head
+of the tracklist.
+If TRACKID is specified, FILENAME is added immediately after TRACKID
+on the existing tracklist.  The final BOOLEAN argument replaces the
+currently playing track with the newly-added one.
+Returns the TRACKID of the newly added track
+
+=item tl clear
+
+Clear current tracklist
+
+=item tl current
+
+Display the pathname to the currently playing track
+
+=item tl current-id
+
+Display the TRACKID of the currently playing track
+
+=item tl remove TRACKID
+
+Remove the track with the given TRACKID from
+the track list and returns the FILENAME if successful
+
+=item tl get [TRACKIDS]
+
+Returns a list of TRACKIDS mapped to shell-escaped filenames.
+
+=item tl goto TRACKID [TIMESTAMP]
+
+Plays the given TRACKID.
+An optional timestamp may be added to prevent playing the
+same part(s) repeatedly
+
+=item tl max [MAXIMUM]
+
+Sets or gets the maximum number of tracks allowed in the tracklist
+
+=item tl next
+
+Jump to the next track in the tracklist
+
+=item tl prev
+
+Jump to the previous track in the tracklist
+
+=item tl repeat [BOOLEAN|1]
+
+Show/or change repeat status of the tracklist.
+With no args, this will show "true", "false", or "1"
+If set to "1", dtas-player will repeat the current track.
+Returns the previous repeat status.
+
+=item tl shuffle [BOOLEAN]
+
+Show/or change the current shuffle status of the tracklist.
+Returns the previous shuffle status.
+
+=item tl swap TRACKID_A TRACKID_B
+
+Swaps the positions of two tracks.
+
+=item tl tracks
+
+Returns a list of all TRACKIDS in the tracklist
+
+=item trim [off|TBEG [TLEN]]
+
+Limits playback of all tracks in the tracklist to the time starting
+at TBEG and ending after TLEN has elapsed.  Not specifying TLEN will
+cause sox.  Like the sox "trim" effect, prefixing TLEN with a '='
+will be interpreted as an absolute stop time.
+Both TBEG and TLEN should be specified in seconds, not sample counts.
+Specifying "off" (without quotes) disables trim.
+This feature is intended to allow users to "zoom-in" on a particular
+portion of a track to tweak parameters (either with
+L<dtas-sourceedit(1)> or via playback of splitfx YAML files) and often
+combined with looping the tracklist (via "tl repeat").
+
+=item watch - adds the client to the passive watch list for notifications.
+
+It is recommended clients issue no further commands and open
+another client socket to issue non-watch commands.
+
+=back
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
diff --git a/Documentation/dtas-player_protocol.txt b/Documentation/dtas-player_protocol.txt
deleted file mode 100644
index 9efd0a1..0000000
--- a/Documentation/dtas-player_protocol.txt
+++ /dev/null
@@ -1,326 +0,0 @@
-% dtas-player_protocol(7) dtas user manual
-%
-
-# NAME
-
-dtas-player_protocol - protocol for controling dtas-player
-
-# DESCRIPTION
-
-NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE - NOTE
-
-I'm considering a heavy revamp of this protocol.  The "OK" responses for
-a lot of commands may not be necessary since this is Unix sockets and
-not TCP, and I may move away from a request-response model and towards
-an entirely listen/notification model.  I have little experience in
-non-TCP-based application protocols, so this is an area of
-experimentation for me.
-
-This must stay over Unix sockets because filesystem permissions are
-needed to enforce code execution permissions.  dtas-player is really a
-shell in disguise, after all.
-
-Protocol feedback greatly appreciated, email us at dtas-all@nongnu.org
-
-*********************************************************
-
-This gives a specification of the dtas-player protocol over a local Unix
-SOCK_SEQPACKET socket.  The dtas-player protocol should NOT be
-considered stable at this point and compatibility will break.
-
-Inspiration is taken from MPRIS and MPRIS 2.0 specifications (e.g.
-play_pause, play, pause), and there will be a proxy in the future to
-support MPRIS/MPRIS 2.0 clients.
-
-The DTAS_PLAYER_SOCK is the standard environment determining the control
-socket for dtas-player(1).  This defaults to $HOME/.dtas/player.sock if
-unset.
-
-Most low-level commands may be issued using the dtas-ctl(1) command.
-
-Higher-level commands such as dtas-console(1), dtas-sourceedit(1),
-dtas-sinkedit(1), and dtas-enq(1) also implement this protocol.
-
-# ARGUMENT TYPES
-
-- BOOLEAN - must be "true" or "false"
-- INTEGER - a signed integer in decimal notation (base 10)
-- UNSIGNED - an unsigned integer in decimal or hex notation
-- ENVNAME - must be a suitable environment variable (setenv(3))
-- ENVVALUE - must be a suitable environment variable (setenv(3))
-- COMMAND, this may be quoted string passed to sh -c "",
-           variable/argument expansion will be performed by the shell
-- SOURCENAME - "sox" or "av", more backends may be supported in the future
-- TIMESTAMP - a time stamp formatted in HH:MM:SS.FRAC (for seeking)
-- TRACKID - a unique unsigned integer in decimal (base-10) representing a
-            track in the tracklist
-- FILENAME - an expanded pathname relative to / is recommended since
-             dtas-player and the client may run in different directories
-
-# VARIABLE EXPANSION
-
-For source and sink "command" arguments, the $SOXFMT and $ECAFMT
-environment variables are exported automatically to source to ease
-integration with sox(1) and ecasound(1).
-
-Both $SOXFMT and $ECAFMT are based on the configured "format" of
-the dtas-player (see below).
-
-For all machines, $SOXFMT defaults to: -ts32 -c2 -r44100
-For little-endian machines, $ECAFMT defaults to: -fs32_le,2,44100
-
-# COMMANDS
-
-Commands here should be alphabetized according to `LC_ALL=C sort'
-
-* cd - change the current working directory of the player
-
-* clear - clear current queue (current track/command continues running)
-  PENDING: this may be renamed to "queue clear" or "queue-clear"
-
-* cue - display the index/offsets of the file based on the embedded
-  cue sheet, if any
-
-* cue next - skip to the next section of the track based on the
-  embedded cue sheet.  This may skip to the next track if there is
-  no embedded cue sheet or if playing the last (embedded) track
-
-* cue prev - skip to the previous section of the track based on
-  the embedded cue sheet.  This may just seek to the beginning
-  if there is no embedded cue sheet or if we are playing the first
-  (embedded) track.
-
-* cue goto INTEGER - go to the embedded track with cue index denoted
-  by INTEGER (0 is first track as returned by "cue").  Negative
-  values of INTEGER allows selecting track relative to the last
-  track (-1 is the last track, -2 is the penultimate, and so on).
-
-* current - output information about the currently-playing track/command
-  in YAML.  The structure of this is unstable and subject to change.
-
-* enq FILENAME - enqueue the given FILENAME for playback
-  An expanded (full) pathname relative to '/' is recommended, as
-  dtas-player and the client may be in different directories.
-  PENDING: this may be renamed to "queue add"
-
-* enq-cmd "COMMAND" - run the following command for playback.
-  The COMMAND is expected to output audio in the audio format matching
-  the current audio format of the player.  This may be a shell pipeline
-  and include multiple commands.  The $SOXFMT and $ECAFMT variables are
-  available here.
-  PENDING: this may be renamed to "queue add-cmd"
-
-* env ENVTOSET=ENVVALUE ENVTOSET2=ENVVALUE2
-  Set environment variables.  This affects all future source/sink
-  processes as well as helper commands dtas-player may spawn
-  (e.g. soxi(1)).  Environment variables set this way are currently not
-  preserved across invocations of dtas-player(1), but may change in the
-  future.
-
-* env ENVTOUNSET1# ENVTOUNSET#
-  Unset the given environment variable.
-  PENDING: the '#' is ugly and inconsistent with the per-sink/source.
-  env.
-
-* format FORMATARGS - configure the format between source and sink
-  Changing this will affect the $SOXFMT and $ECAFMT environments passed
-  to source and sink commands.  Changing this implies a "restart"
-  Changing rate to 48000 is probably useful if you plan on playing to some
-  laptop sound cards.  In all cases where "bypass" is supported, it
-  removes the guarantee of gapless playback as the audio device(s)
-  will likely need to be restarted.
-
-
-    + channels=(UNSIGNED|bypass) - (default: 2 (stereo)) - number of
-      channels to use internally.  sox will internally invoke the remix
-      effect when decoding.  This supports the value "bypass" (without
-      quotes) to avoid the automatic remix effect.  Using "bypass" mode
-      removes the guarantee of gapless playback, as the audio device will
-      likely need to be restarted, introducing an audible gap.
-    + endian=(big|little|swap) - (default: native) - there is probably no
-      point in changing this unless you output over a network sink to
-      a machine of different endianess.
-    + bits=(UNSIGNED|bypass) - (default: implied from type) - sample precision
-      (decoded)
-      This may be pointless and removed in the future, since the sample
-      precision is implied from type.  This supports the value of "bypass"
-      to avoid dither/truncation in later stages.
-    + rate=(UNSIGNED|bypass) - (default: 44100) - sample rate of audio
-      Typical values of rate are 44100, 48000, 88200, 96000.  Not all
-      DSP effects are compatible with all sampling rates/channels.
-      This supports the value of "bypass" as well to avoid introducing
-      software resamplers into the playback chain.
-    + type=(s16|s24|s32|u16|u24|u32|f32|f64) - (default: s32)
-      change the raw PCM format.  s32 currently offers the best performance
-      when only sox/play are used.  f32 may offer better performance if
-      piping to/from non-sox applications (e.g. ecasound)
-
-* pause - pause playback
-  Player pause state is preserved across dtas-player invocations.
-
-* play - restart playback from pause.  Playback sinks will yield
-  control of the audio playback device once no source is playing.
-
-* play_pause - toggle the play/pause state.  This starts playback if
-  paused, and pauses playback if playing.
-
-* queue cat - dump the contents of the queue as YAML
-  This may include arbitrary commands to be executed, filenames,
-  and offsets for playback.  The format is not intended to be
-  stable and subject to internal changes in dtas-player.
-
-* restart - restarts all processes in the current pipeline.  Playback
-  will be momentarily interrupted while this change occurs.  This is
-  necessary if one of the commands (e.g. sox or ecasound) or loaded
-  libraries (e.g. a LADSPA plugin) is upgraded.  Use "source restart"
-  instead to only restart the source chain, leaving the sinks
-  untouched.
-
-* rg RGARGS - configure ReplayGain support
-  All FLOAT values may be adjusted via '+=' or '-=' instead of simple
-  assignment ('=').  If RGARGS is empty, the current rg state of
-  non-default values will be dumped in YAML.
-    + fallback_gain=FLOAT (-6.0) - dB value
-      Adjust the volume by this level (usually negative) for tracks
-      missing ReplayGain tags.  This is useful when the queue contains
-      a mix of tracks with and without ReplayGain tags.
-    + fallback_track=BOOLEAN (true)
-      When in album_gain mode, fallback to track_gain if the
-      REPLAYGAIN_ALBUM_GAIN metadata is missing.
-    + mode=(album_gain|track_gain|track_norm|album_norm|off)
-      This controls the ReplayGain tag to use.  The *_norm options
-      are used for peak normalization and not commonly found in other
-      players.
-    + preamp=FLOAT (0) - dB value
-      Adjust the album_gain or track_gain amount by this value (in dB).
-    + norm_level=FLOAT (1.0 == dBFS)
-      Controls the level to normalize to when using album_norm or track_norm.
-
-* seek [+-]TIMESTAMP - seek the current track to a specified time.
-  This is passed directly as the first argument for the sox(1) "trim"
-  command.   See the sox(1) manpage for details.
-  Seeking to a relative time is also supported by prefixing the time
-  with '+' or '-'
-
-* skip - abort current track/command (via closing the output pipe)
-  Running the "clear" command before this will abort playback.
-
-* sink ls - list names of current sinks
-
-* sink cat SINKNAME - dump SINKNAME config in YAML
-
-* sink rm SINKNAME - remove SINKNAME
-
-* sink ed SINKNAME SINKARGS - create/edit SINKNAME
-  This currently does not restart running (active) sinks.
-  This will stop active sinks if active is set to false, and start
-  active sinks if active is set to true.
-  See dtas-sinkedit(1) for an example of using this.
-    + command=COMMAND - change the command-line used for playback
-    + active=BOOLEAN - whether or not the sink will be in use (default: false)
-    + env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the sink process
-    + env#ENVNAME - unset ENVNAME in the sink process (only)
-    + prio=INTEGER - priority of the sink, lower values run first
-    + nonblock=BOOLEAN - drop audio data to avoid holding back other sinks
-    + pipe_size=UNSIGNED - set the size of the pipe for the sink (Linux-only)
-
-* source cat SOURCENAME - dump the current source command and env in YAML
-
-* source ed SOURCENAME SOURCEARGS - edit the source parameters.
-  This changes here will immediately restart the source process.
-  See the code for dtas-sourceedit(1) for an example of using this.
-    + command=COMMAND - change the command-line used to decode audio
-    + env.ENVNAME=ENVVALUE - set ENVNAME to ENVVALUE for the source process
-    + env#ENVNAME - unset ENVNAME in the source process (only)
-    + tryorder=INTEGER - lower values are tried first
-    PENDING: tryorder here is wrong and may be removed or changed.
-    We need to account for at least two variables input file:
-        1. input type (flac/opus/mp3/etc)
-        2. transport protocol (local FS/http/ftp/sftp/etc)
-
-* source ls - dump the names of sources sorted by tryorder
-
-* source restart - restart the current source command
-  This can be useful if the source file is changed during playback
-  and the current player process is holding onto an unlinked inode.
-  This is advantageous over a full "restart" as there is no audible
-  gap on most systems.
-
-* state dump [FILENAME]
-  Immediately dump the state of the player.  If a FILENAME is specified,
-  the state is written to that file.  Otherwise, the default state file
-  (configured via DTAS_PLAYER_STATE environment variable, defaulting
-  to ~/.dtas/player_state.yml) is written to.  This does not use fsync(2),
-  users requiring fsync should open(2) that file and fsync(2) it
-  themselves if necessary.
-
-* tl add FILENAME [TRACKID [BOOLEAN]] - add files to the tracklist
-  With one arg, adds FILENAME to the head of the tracklist.
-  If TRACKID is specified, FILENAME is added immediately after TRACKID
-  on the existing tracklist.  The final BOOLEAN argument replaces the
-  currently playing track with the newly-added one.
-  Returns the TRACKID of the newly added track
-
-* tl clear - clear current tracklist
-
-* tl current - display the pathname to the currently playing track
-
-* tl current-id - display the TRACKID of the currently playing track
-
-* tl remove TRACKID - remove the track with the given TRACKID from
-  the track list and returns the FILENAME if successful
-
-* tl get [TRACKIDS]
-  returns a list of TRACKIDS mapped to shell-escaped filenames.
-
-* tl goto TRACKID [TIMESTAMP] - plays the given TRACKID
-  An optional timestamp may be added to prevent playing the
-  same part(s) repeatedly
-
-* tl max [MAXIMUM] - sets or gets the maximum number of tracks
-  allowed in the tracklist
-
-* tl next - jump to the next track in the tracklist
-
-* tl prev - jump to the previous track in the tracklist
-
-* tl repeat [BOOLEAN|1] - show/or change repeat status of the tracklist.
-  With no args, this will show "true", "false", or "1"
-  If set to "1", dtas-player will repeat the current track.
-  Returns the previous repeat status.
-
-* tl shuffle [BOOLEAN] - show/or change the current shuffle status of
-  the tracklist.  Returns the previous shuffle status.
-
-* tl swap TRACKID_A TRACKID_B - swaps the positions of two tracks.
-
-* tl tracks
-  returns a list of all TRACKIDS in the tracklist
-
-* trim [off|TBEG [TLEN]]
-  Limits playback of all tracks in the tracklist to the time starting
-  at TBEG and ending after TLEN has elapsed.  Not specifying TLEN will
-  cause sox.  Like the sox "trim" effect, prefixing TLEN with a '='
-  will be interpreted as an absolute stop time.
-  Both TBEG and TLEN should be specified in seconds, not sample counts.
-  Specifying "off" (without quotes) disables trim.
-  This feature is intended to allow users to "zoom-in" on a particular
-  portion of a track to tweak parameters (either with
-  dtas-sourceedit(1) or via playback of splitfx YAML files) and often
-  combined with looping the tracklist (via "tl repeat").
-
-* watch - adds the client to the passive watch list for notifications.
-  It is recommended clients issue no further commands and open
-  another client socket to issue non-watch commands.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
diff --git a/Documentation/dtas-player_sink_examples.txt b/Documentation/dtas-player_sink_examples.pod
index 80d33c4..da8ea76 100644
--- a/Documentation/dtas-player_sink_examples.txt
+++ b/Documentation/dtas-player_sink_examples.pod
@@ -1,19 +1,20 @@
 % dtas-player_sink_examples(7) dtas user manual
 
-# NAME
+=head1 NAME
 
 dtas-player_sink_examples - sink examples for dtas-player
 
-# SYNOPSIS
+=head1 SYNOPSIS
 
 dtas-ctl sink ed SINKNAME command='...'
+
 dtas-sinkedit SINKNAME
 
-# EXAMPLES
+=head1 EXAMPLES
 
-## Streaming Ogg-Vorbis to Icecast
+=head2 Streaming Ogg-Vorbis to Icecast
 
-To use oggfwd(1) and Icecast, the following sink works.
+To use L<oggfwd(1)> and Icecast, the following sink works.
 Warning: the following example will likely expose your Icecast source
 password to any local users on the system.
 
@@ -22,9 +23,9 @@ password to any local users on the system.
     name: oggfwd
     command: sox $SOXFMT - -t ogg - | oggfwd $HOST $PORT $PASS /dtas.ogg
 
-## Stream to a remote host via ssh
+=head2 Stream to a remote host via ssh
 
-Alternatively, if you have play(1) installed on any remote host and
+Alternatively, if you have L<play(1)> installed on any remote host and
 a slow connection using Ogg-Vorbis:
 
     # Long lines in YAML can be broken up and the subsequent lines
@@ -46,12 +47,12 @@ the above Ogg-Vorbis example.
     name: ssh-remote
     command: ssh $HOST env AUDIODEV=... play -q $SOXFMT -
 
-## Dump audio to a file during playback
+=head2 Dump audio to a file during playback
 
 To configure a dumper sink (in addition to the "default" sink).  Note
 the use of $SOXFMT, this will be automatically expanded to match the
 internal format of the player.  The internal format of the player is
-described in dtas-player_protocol(7).
+described in L<dtas-player_protocol(7)>.
 
     $ dtas-ctl sink ed dumper command='sox $SOXFMT - /tmp/dump.sox'
 
@@ -61,23 +62,26 @@ Non-"default" sinks are not active by default, but may be made active.
 
 Changing it again to "active=false" will deactivate the sink.
 
-## Apply a short delay to low frequencies to improve time-alignment
+=head2 Apply a short delay to low frequencies to improve time-alignment
+
+See L<dtas-xdelay(1)>.
 
-See dtas-xdelay(1).
+=head1 CONTACT
 
-# CONTACT
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
 
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
 No subscription is necessary to post to the mailing list.
 
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
 
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 
-# SEE ALSO
+=head1 SEE ALSO
 
-dtas-ctl(1), dtas-sinkedit(1), dtas-xdelay(1),
-sox(1), play(1), oggfwd(1), ssh(1), ssh_config(5), env(1)
+L<dtas-ctl(1)>, L<dtas-sinkedit(1)>, L<dtas-xdelay(1)>,
+L<sox(1)>, L<play(1)>, L<oggfwd(1)>, L<ssh(1)>, L<ssh_config(5)>, L<env(1)>
diff --git a/Documentation/dtas-sinkedit.txt b/Documentation/dtas-sinkedit.pod
index 07f8ecb..98dee27 100644
--- a/Documentation/dtas-sinkedit.txt
+++ b/Documentation/dtas-sinkedit.pod
@@ -1,36 +1,43 @@
 % dtas-sinkedit(1) dtas user manual
-%
 
-# NAME
+=head1 NAME
 
 dtas-sinkedit - edit the command and environment of a sink
 
-# SYNOPSYS
+=head1 SYNOPSYS
 
 dtas-sinkedit SINKNAME
 
-# DESCRIPTION
+=head1 DESCRIPTION
 
 dtas-sinkedit spawns an editor to allow editing of a sink as a YAML file.
-See dtas-player_protocol(7) for details on SINKARGS.
+See L<dtas-player_protocol(7)> for details on SINKARGS.
 
-On Linux machines with the sleepy_penguin RubyGem installed, inotify(7)
+On Linux machines with the sleepy_penguin RubyGem installed, L<inotify(7)>
 is used to monitor the file for changes while the text exitor is running.
 Each time a user finishes saving a file, changes are committed immediately.
 This behavior may be disabled by using the -N or --no-watch command-line
 switch.
 
-# OPTIONS
--N, \--no-watch
-:   Disable inotify(7) support on Linux systems
+=head1 OPTIONS
 
--n, \--dry-run
-:   Only print commands which would be sent to dtas-player
+=over
 
--V, \--verbose
-:   Print out commands as they are sent to dtas-player
+=item -N, --no-watch
 
-# EXAMPLES
+Disable L<inotify(7)> support on Linux systems
+
+=item -n, --dry-run
+
+Only print commands which would be sent to dtas-player
+
+=item -V, --verbose
+
+Print out commands as they are sent to dtas-player
+
+=back
+
+=head1 EXAMPLES
 
 To get a list of existing sink names
 
@@ -45,25 +52,28 @@ If SINKNAME was not listed, it will be created (in an inactive state).
 Successfully exiting your text editor will send the changes to the
 running dtas-player.
 
-# ENVIRONMENT
+=head1 ENVIRONMENT
 
 VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
 
 DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
 This defaults to ~/.dtas/player.sock
 
-# CONTACT
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
 
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
 No subscription is necessary to post to the mailing list.
 
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
 
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 
-# SEE ALSO
+=head1 SEE ALSO
 
-dtas-player(1), dtas-player_protocol(7), dtas-ctl(1)
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-ctl(1)>
diff --git a/Documentation/dtas-sourceedit.txt b/Documentation/dtas-sourceedit.pod
index 8e87008..69062b1 100644
--- a/Documentation/dtas-sourceedit.txt
+++ b/Documentation/dtas-sourceedit.pod
@@ -1,40 +1,46 @@
 % dtas-sourceedit(1) dtas user manual
-%
 
-# NAME
+=head1 NAME
 
 dtas-sourceedit - edit parameters of a source decoder
 
-# SYNOPSYS
+=head1 SYNOPSYS
 
 dtas-sourceedit {sox | av | ff}
 
-# DESCRIPTION
+=head1 DESCRIPTION
 
 dtas-sourceedit spawns an editor to allow editing of a source as a YAML file.
-See dtas-player_protocol(7) for details on SOURCEARGS.  If standard input is
-a pipe or file, it is parsed as YAML and fed to the dtas-player(1) instance
+See L<dtas-player_protocol(7)> for details on SOURCEARGS.  If standard input is
+a pipe or file, it is parsed as YAML and fed to the L<dtas-player(1)> instance
 non-interactively.  This is useful for loading various profiles from the
 filesystem.
 
-On Linux machines with the sleepy_penguin RubyGem installed, inotify(7)
+On Linux machines with the sleepy_penguin RubyGem installed, L<inotify(7)>
 is used to monitor the file for changes while the text exitor is running.
 Each time a user finishes saving a file, changes are committed immediately.
 This behavior may be disabled by using the -N or --no-watch command-line
 switch.
 
-# OPTIONS
+=head1 OPTIONS
 
--N, \--no-watch
-:   Disable inotify(7) support on Linux systems
+=over
 
--n, \--dry-run
-:   Only print commands which would be sent to dtas-player
+=item -N, --no-watch
 
--V, \--verbose
-:   Print out commands as they are sent to dtas-player
+Disable L<inotify(7)> support on Linux systems
 
-# EXAMPLES
+=item -n, --dry-run
+
+Only print commands which would be sent to dtas-player
+
+=item -V, --verbose
+
+Print out commands as they are sent to dtas-player
+
+=back
+
+=head1 EXAMPLES
 
 Invoking dtas-sourceedit will spawn your favorite text editor on "sox":
 
@@ -53,25 +59,28 @@ To change the way dtas-player calls ffmpeg (lightly-tested):
 
         $ dtas-sourceedit ff
 
-# ENVIRONMENT
+=head1 ENVIRONMENT
 
 VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
 
 DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
 This defaults to ~/.dtas/player.sock
 
-# CONTACT
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
 
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
 No subscription is necessary to post to the mailing list.
 
-# COPYRIGHT
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
 
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 
-# SEE ALSO
+=head1 SEE ALSO
 
-dtas-player(1), dtas-player_protocol(7), dtas-ctl(1)
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-ctl(1)>
diff --git a/Documentation/dtas-splitfx.pod b/Documentation/dtas-splitfx.pod
new file mode 100644
index 0000000..4ffe24f
--- /dev/null
+++ b/Documentation/dtas-splitfx.pod
@@ -0,0 +1,271 @@
+% dtas-splitfx(1) dtas user manual
+
+=head1 NAME
+
+dtas-splitfx - split audio and apply effects to all tracks
+
+=head1 SYNOPSIS
+
+dtas-splitfx SPLITFX_FILE.yml [OPTIONS] [TARGETS] [ARGS...]
+
+=head1 DESCRIPTION
+
+dtas-splitfx reads as YAML file and can apply effects (including
+resampling/dither), split, tag, and encode files in parallel.
+dtas-splitfx is intended for splitting recordings from vinyl and live
+concerts into separate files.  dtas-splitfx is inspired by cuesheets for
+CD audio and the L<make(1)> build tool.
+
+dtas-splitfx primarily uses L<sox(1)>, but it is possible to define targets
+to use L<ecasound(1)>, too.
+
+=head1 OPTIONS
+
+=over
+
+=item -j, --jobs [JOBS]
+
+Number of jobs to run in parallel.  If no number is specified, all
+jobs are run in parallel.
+
+=item -n, --dry-run
+
+Print, but do not run the commands to be executed
+
+=item -s, --quiet, --silent
+
+Silent operation, commands are not printed as executed
+
+=item -D, --no-dither
+
+Disable automatic setting of the DITHERFX env.  This also passes
+the option to L<sox(1)> via SOX_OPTS.
+
+=item -O, --outdir OUTDIR
+
+Set output directory instead of current directory.
+User-created targets must allow a placeholder for the
+(by default, an empty string) $OUTDIR environment variable
+in the output command.
+
+=item -C, --compression FACTOR
+
+Set the compression factor passed to L<sox(1)>.  See L<soxformat(7)>
+for more information on how it works across different formats.
+
+=item -r, --rate RATE
+
+Override the output sample rate in the specified TARGET
+
+=item -b, --bits BITS
+
+Override the output bit depth in the specified TARGET
+
+=item -t, --trim POSITION
+
+Passes a POSITION argument to the sox "trim" effect to allow
+limiting output to only process a portion of the original.
+This bypasses the "tracks" section and of the YAML file and
+outputs the result as a single file with the TRACKNUMBER
+of "000".  For ease-of-typing, commas in this command-line
+argument are automatically expanded to spaces when passed to sox.
+
+=item -p, --sox-pipe
+
+Used in place of an output target to specify outputting audio data in
+the native "sox" format to another L<sox(1)> or L<play(1)> command.  This
+moves printing of output to stderr and disables parallel job invocation.
+
+=back
+
+=head1 FILE FORMAT
+
+=over
+
+=item infile - string, the pathname of the original audio file
+
+=item env - ordered hash of environment variables to set for all commands
+
+    env: !omap
+      FX: gain 3 stats
+
+=item comments - hash of common tags for all audio (e.g. ARTIST, ALBUM, YEAR)
+
+    comments:
+      ARTIST: John Smith
+      ALBUM: Hello World
+      YEAR: 2013
+
+=item track_start - integer, number to start the track count at
+
+default: 1
+
+=item cdda_align - boolean, enforce sector alignment for audio CDs
+
+default: false
+
+=item track_zpad - boolean or integer
+
+Zero-pad the TRACKNUMBER in metadata and
+filenames.  If an integer, this creates a fixed padding even if the
+padding is not necessary.  If true, this only pads as needed for the
+highest-numbered track.  Default: true
+
+=item tracks - array, see "TRACKS" section
+
+=item targets - hash, see "TARGETS" section
+
+=item command - used only by L<dtas-player(1)>
+
+=back
+
+=head1 TRACKS
+
+Tracks may be defined by a start time, with the stop time defined
+automatically by the start of the next track, stop time, or a skip
+segment.
+
+=over
+
+=item t TIME TITLE [fade_in/fade_out=FADE_ARGS]
+
+The start of a new track
+at TIME with TITLE.  An optional fade_in and fade_out may be specified
+for the first/last tracks.
+
+=item skip TIME - skip a segment starting at TIME
+
+"skip" segments are
+useful for skipping long gaps between tracks (such as flipping vinyl
+or intermission at concerts)
+
+=item stop TIME - stop the last track
+
+This should be the last directive in the "tracks" array.
+
+=back
+
+An example of the tracks array for a 4 track EP follows:
+
+    tracks:
+      - t  0:21    "This is the first track of an EP" fade_in='t 1'
+      - t  7:11.6  "Second track of side A of an EP"
+      - skip 9:18  # this is where I flip the record, comments are allowed
+      - t  9:41    "3rd track of an EP"
+      - t 13:36.5  "Final track of the EP" fade_out='t 1'
+      - stop 18:11
+
+=head1 FADES
+
+dtas-splitfx automatically sets up fade-in/fade-out effects for sox(1)
+based on track times.  These are to be used in "t" (track) directives in
+the "tracks" array:
+
+=over
+
+=item fade_in="[TYPE] LENGTH"
+
+=item fade_out="[TYPE] LENGTH"
+
+=back
+
+TYPE is optional, but LENGTH is required.  See L<sox(1)> for a description
+of the fade type.
+
+=head1 ENVIRONMENT
+
+dtas-splitfx sets several default environment variables for commands to
+use in targets:
+
+=over
+
+=item INFILE - this matches the "infile" directive in the YAML file
+
+=item INDIR - the directory INFILE belongs to, without trailing slash
+
+=item INBASE - the basename of INFILE
+
+=item TBEG - the integer sample offset where the L<sox(1)> trim effect starts
+
+=item TLEN - the integer sample count representing the length of the trim
+
+=item TRIMFX - essential
+
+Supplies the necessary L<sox(1)> trim effect to
+each track. In other words, this is: "trim ${TBEG}s ${TLEN}s"
+
+=item COMMENTS - expands to --comment-file=PATH for L<sox(1)>
+
+=item OUTDIR - placeholder for --outdir, defaults to an empty string
+
+=item SUFFIX - the suffix of the output format without "." (e.g. "flac", "ogg")
+
+=item TRACKNUMBER - the track number, useful for comments and filenames
+
+=item RATEFX - rate effect and arguments for L<sox(1)> resampling
+
+=item DITHERFX - dither effect and arguments for L<sox(1)> dithering
+
+=item FX - any user-specified sox effects which encompases the entire file.
+
+(e.g. "highpass 35 gain 3 stats")
+
+=back
+
+=head1 TARGETS
+
+The default targets will split audio and avoid applying any effects.
+They are named after common audio formats supported by L<sox(1)>:
+
+=over
+
+=item flac
+
+=item ogg
+
+=item mp3
+
+=item sox
+
+=back
+
+If not specified, "flac" is the default target.
+
+Additional targets supported by default.
+
+=over
+
+=item flac-cdda
+
+This encodes the audio to "flac" format while being
+easily decompressible to a format suitable for being burned to audio CD.
+
+=back
+
+Custom targets may easily be defined to apply effects and gain.  For
+example, the following "flac24" target raises the volume of the left
+channel by 9.5dB and the right one by 8.5dB to compensate for channel
+imbalance in a live concert recording from the audience:
+
+    targets:
+      flac24:
+        command: sox -M
+          "|sox $INFILE -c1 -p $TRIMFX remix 1v1 gain 9.5"
+          "|sox $INFILE -c1 -p $TRIMFX remix 2v1 gain 8.5"
+          $COMMENTS $OUTFMT
+          ${OUTDIR}bandYYYY-MM-DD.FOO.t0"$TRACKNUMBER.$SUFFIX"
+          $RATEFX $DITHERFX stats
+        format:
+          type: flac
+          bits: 24
+          rate: 48000
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<sox(1)>, L<ecasound(1)>, L<flac(1)>, L<dtas-player(1)>
diff --git a/Documentation/dtas-splitfx.txt b/Documentation/dtas-splitfx.txt
deleted file mode 100644
index 352c0a5..0000000
--- a/Documentation/dtas-splitfx.txt
+++ /dev/null
@@ -1,188 +0,0 @@
-% dtas-splitfx(1) dtas user manual
-
-# NAME
-
-dtas-splitfx - split audio and apply effects to all tracks
-
-# SYNOPSIS
-
-dtas-splitfx SPLITFX_FILE.yml [OPTIONS] [TARGETS] [ARGS...]
-
-# DESCRIPTION
-
-dtas-splitfx reads as YAML file and can apply effects (including
-resampling/dither), split, tag, and encode files in parallel.
-dtas-splitfx is intended for splitting recordings from vinyl and live
-concerts into separate files.  dtas-splitfx is inspired by cuesheets for
-CD audio and the make(1) build tool.
-
-dtas-splitfx primarily uses sox(1), but it is possible to define targets
-to use ecasound(1), too.
-
-# OPTIONS
-
--j, \--jobs [JOBS]
-:    Number of jobs to run in parallel.  If no number is specified, all
-     jobs are run in parallel.
-
--n, \--dry-run
-:    Print, but do not run the commands to be executed
-
--s, \--quiet, \--silent
-:    Silent operation, commands are not printed as executed
-
--D, \--no-dither
-:    Disable automatic setting of the DITHERFX env.  This also passes
-    the option to sox(1) via SOX_OPTS.
-
--O, \--outdir OUTDIR
-:    Set output directory instead of current directory.
-    User-created targets must allow a placeholder for the
-    (by default, an empty string) $OUTDIR environment variable
-    in the output command.
-
--C, \--compression FACTOR
-:    Set the compression factor passed to sox(1).  See soxformat(7)
-    for more information on how it works across different formats.
-
--r, \--rate RATE
-:    Override the output sample rate in the specified TARGET
-
--b, \--bits BITS
-:    Override the output bit depth in the specified TARGET
-
--t, \--trim POSITION
-:    Passes a POSITION argument to the sox "trim" effect to allow
-     limiting output to only process a portion of the original.
-     This bypasses the "tracks" section and of the YAML file and
-     outputs the result as a single file with the TRACKNUMBER
-     of "000".  For ease-of-typing, commas in this command-line
-     argument are automatically expanded to spaces when passed to sox.
-
--p, \--sox-pipe
-:    Used in place of an output target to specify outputting audio data in
-     the native "sox" format to another sox(1) or play(1) command.  This
-     moves printing of output to stderr and disables parallel job invocation.
-
-# FILE FORMAT
-
-* infile - string, the pathname of the original audio file
-* env - ordered hash of environment variables to set for all commands
-    env: !omap
-      FX: gain 3 stats
-* comments - hash of common tags for all audio (e.g. ARTIST, ALBUM, YEAR)
-    comments:
-      ARTIST: John Smith
-      ALBUM: Hello World
-      YEAR: 2013
-* track_start - integer, number to start the track count at (default: 1)
-* cdda_align - boolean, enforce sector alignment for audio CDs (default: false)
-* track_zpad - boolean or integer.  Zero-pad the TRACKNUMBER in metadata and
-  filenames.  If an integer, this creates a fixed padding even if the
-  padding is not necessary.  If true, this only pads as needed for the
-  highest-numbered track (default: true)
-* tracks - array, see "TRACKS" section
-* targets - hash, see "TARGETS" section
-* command - used only by dtas-player(1)
-
-# TRACKS
-
-Tracks may be defined by a start time, with the stop time defined
-automatically by the start of the next track, stop time, or a skip
-segment.
-
-* t TIME TITLE [fade_in/fade_out=FADE_ARGS] - the start of a new track
-  at TIME with TITLE.  An optional fade_in and fade_out may be specified
-  for the first/last tracks.
-* skip TIME - skip a segment starting at TIME.  "skip" segments are
-  useful for skipping long gaps between tracks (such as flipping vinyl
-  or intermission at concerts)
-* stop TIME - stop the last track  This should be the last directive in
-  the "tracks" array.
-
-An example of the tracks array for a 4 track EP follows:
-
-    tracks:
-      - t  0:21    "This is the first track of an EP" fade_in='t 1'
-      - t  7:11.6  "Second track of side A of an EP"
-      - skip 9:18  # this is where I flip the record, comments are allowed
-      - t  9:41    "3rd track of an EP"
-      - t 13:36.5  "Final track of the EP" fade_out='t 1'
-      - stop 18:11
-
-# FADES
-
-dtas-splitfx automatically sets up fade-in/fade-out effects for sox(1)
-based on track times.  These are to be used in "t" (track) directives in
-the "tracks" array:
-
-* fade_in="[TYPE] LENGTH"
-* fade_out="[TYPE] LENGTH"
-
-TYPE is optional, but LENGTH is required.  See sox(1) for a description
-of the fade type.
-
-# ENVIRONMENT
-
-dtas-splitfx sets several default environment variables for commands to
-use in targets:
-
-* INFILE - this matches the "infile" directive in the YAML file
-* INDIR - the directory INFILE belongs to, without trailing slash
-* INBASE - the basename of INFILE
-* TBEG - the integer sample offset where the sox(1) trim effect starts
-* TLEN - the integer sample count representing the length of the trim
-* TRIMFX - essential, this supplys the necessary sox(1) trim effect to
-  each track. In other words, this is: "trim ${TBEG}s ${TLEN}s"
-* COMMENTS - expands to --comment-file=PATH for sox(1)
-* OUTDIR - placeholder for --outdir, defaults to an empty string
-* SUFFIX - the suffix of the output format without "." (e.g. "flac", "ogg")
-* TRACKNUMBER - the track number, useful for comments and filenames
-* RATEFX - rate effect and arguments for sox(1) resampling
-* DITHERFX - dither effect and arguments for sox(1) dithering
-* FX - any user-specified sox effects which encompases the entire file.
-  (e.g. "highpass 35 gain 3 stats")
-
-# TARGETS
-
-The default targets will split audio and avoid applying any effects.
-They are named after common audio formats supported by sox(1):
-
-* flac
-* ogg
-* mp3
-* sox
-
-If not specified, "flac" is the default target.
-
-Additional targets supported by default.
-
-* flac-cdda - this encodes the audio to "flac" format while being
-  easily decompressible to a format suitable for being burned to audio CD.
-
-Custom targets may easily be defined to apply effects and gain.  For
-example, the following "flac24" target raises the volume of the left
-channel by 9.5dB and the right one by 8.5dB to compensate for channel
-imbalance in a live concert recording from the audience:
-
-    targets:
-      flac24:
-        command: sox -M
-          "|sox $INFILE -c1 -p $TRIMFX remix 1v1 gain 9.5"
-          "|sox $INFILE -c1 -p $TRIMFX remix 2v1 gain 8.5"
-          $COMMENTS $OUTFMT
-          ${OUTDIR}bandYYYY-MM-DD.FOO.t0"$TRACKNUMBER.$SUFFIX"
-          $RATEFX $DITHERFX stats
-        format:
-          type: flac
-          bits: 24
-          rate: 48000
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-sox(1), ecasound(1), flac(1), dtas-player(1)
diff --git a/Documentation/dtas-tl.pod b/Documentation/dtas-tl.pod
new file mode 100644
index 0000000..44bdfbb
--- /dev/null
+++ b/Documentation/dtas-tl.pod
@@ -0,0 +1,122 @@
+% dtas-tl(1) dtas user manual
+
+=head1 NAME
+
+dtas-tl - tracklist manipulation for dtas-player (development)
+
+=head1 SYNOPSYS
+
+dtas-tl [COMMANDS]
+
+=head1 DESCRIPTION
+
+dtas-tl provides utility functions for manipulating the tracklist of the
+dtas-player (not the queue, the tracklist is separate from the queue).
+It is mainly intended as a development tool and will likely go away in
+the future or have its functionality merged into another tool (or MPRIS
+client).
+
+=head1 COMMANDS
+
+=over
+
+=item aac - B<A>dd tracks B<A>fter B<C>urrent track in the tracklist
+
+=item addhead - add tracks to the beginning of the tracklist
+
+=item addtail - add tracks to the end of the tracklist
+
+=item current - display the current track, "NONE" if not playing
+
+=item current-id - display the TRACKID of the current track
+
+"NONE" if not playing
+
+=item cat - display a newline-delimited list of TRACK_ID=PATH output
+
+=item clear - remove all tracks from the tracklist
+
+=item edit - spawn an editor to allow editing the tracklist as a text file
+
+See EDITING for more information.
+
+=item goto TRACKID [POS]
+
+Play TRACKID immediately, optionally seek to POS
+TRACKID may be looked up via cat, and POS should be a timestamp in
+HH:MM:SS.FRAC format.
+
+=item reto REGEXP [POS]
+
+Play first track with path matching REGEXP immediately,
+optionally seek to POS.  POS should be a timestamp in HH:MM:SS.FRAC format.
+
+=item next - play the next track in the tracklist
+
+=item prev - play the previous track in the tracklist
+
+=item repeat 1 - repeat the current track
+
+=item repeat false - disable repeat
+
+=item repeat true - enable repeat of the whole tracklist
+
+=back
+
+See L<dtas-player_protocol(7)> for a detailed description of the protocol.
+
+=head1 EXAMPLES
+
+display the current tracklist
+
+        $ dtas-tl cat
+
+to add an an entire directory of FLAC files
+
+        $ dtas-tl addtail /path/to/directory/*.flac
+
+to skip forward in the tracklist
+
+        $ dtas-tl next
+
+to skip backwards in the tracklist
+
+        $ dtas-tl prev
+
+=head1 EDITING
+
+It is possible to edit the player tracklist from your favorite text
+editor.  Existing lines denoting tracks may be rearranged, deleted,
+copied or entirely new lines with path names (without a trailing
+"=TRACK_ID") may be added.
+
+Changes to the tracklist are sent to the player when the user exits the
+editor.  This functionality only works when there is one user editing
+the tracklist at a time, and when no files in the tracklist contain rare
+newline characters.
+
+=head1 ENVIRONMENT
+
+VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
+
+DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
+This defaults to ~/.dtas/player.sock
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-ctl(1)>
diff --git a/Documentation/dtas-tl.txt b/Documentation/dtas-tl.txt
deleted file mode 100644
index 2ff5ff6..0000000
--- a/Documentation/dtas-tl.txt
+++ /dev/null
@@ -1,96 +0,0 @@
-% dtas-tl(1) dtas user manual
-
-# NAME
-
-dtas-tl - tracklist manipulation for dtas-player (development)
-
-# SYNOPSYS
-
-dtas-tl [COMMANDS]
-
-# DESCRIPTION
-
-dtas-tl provides utility functions for manipulating the tracklist of the
-dtas-player (not the queue, the tracklist is separate from the queue).
-It is mainly intended as a development tool and will likely go away in
-the future or have its functionality merged into another tool (or MPRIS
-client).
-
-# COMMANDS
-
-* aac - *A*dd tracks *A*fter *C*urrent track in the tracklist
-* addhead - add tracks to the beginning of the tracklist
-* addtail - add tracks to the end of the tracklist
-* current - display the current track, "NONE" if not playing
-* current-id - display the TRACKID of the current track
-  "NONE" if not playing
-* cat - display a newline-delimited list of TRACK_ID=PATH output
-  Note: this is shell-escaped, multibyte characters may not show up properly.
-* clear - remove all tracks from the tracklist
-* edit - spawn an editor to allow editing the tracklist as a text file
-  See EDITING for more information.
-* goto TRACKID [POS] - play TRACKID immediately, optionally seek to POS
-TRACKID may be looked up via cat, and POS should be a timestamp in
-HH:MM:SS.FRAC format.
-* reto REGEXP [POS] - play first track with path matching REGEXP immediately,
-optionally seek to POS.  POS should be a timestamp in HH:MM:SS.FRAC format.
-* next - play the next track in the tracklist
-* prev - play the previous track in the tracklist
-* repeat 1 - repeat the current track
-* repeat false - disable repeat
-* repeat true - enable repeat of the whole tracklist
-
-See dtas-player_protocol(7) for a detailed description of the protocol.
-
-# EXAMPLES
-
-display the current tracklist
-
-        $ dtas-tl cat
-
-to add an an entire directory of FLAC files
-
-        $ dtas-tl addtail /path/to/directory/*.flac
-
-to skip forward in the tracklist
-
-        $ dtas-tl next
-
-to skip backwards in the tracklist
-
-        $ dtas-tl prev
-
-# EDITING
-
-It is possible to edit the player tracklist from your favorite text
-editor.  Existing lines denoting tracks may be rearranged, deleted,
-copied or entirely new lines with path names (without a trailing
-"=TRACK_ID") may be added.
-
-Changes to the tracklist are sent to the player when the user exits the
-editor.  This functionality only works when there is one user editing
-the tracklist at a time, and when no files in the tracklist contain rare
-newline characters.
-
-# ENVIRONMENT
-
-VISUAL / EDITOR - your favorite *nix text editor, defaults to 'vi' if unset.
-
-DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
-This defaults to ~/.dtas/player.sock
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-dtas-player(1), dtas-player_protocol(7), dtas-ctl(1)
diff --git a/Documentation/dtas-xdelay.pod b/Documentation/dtas-xdelay.pod
new file mode 100644
index 0000000..e8628a5
--- /dev/null
+++ b/Documentation/dtas-xdelay.pod
@@ -0,0 +1,96 @@
+% dtas-xdelay(1) dtas user manual
+
+=head1 NAME
+
+dtas-xdelay - play audio with a crossover delay
+
+=head1 SYNOPSYS
+
+dtas-xdelay [OPTIONS] INPUT1 INPUT2 DELAY
+
+=head1 DESCRIPTION
+
+dtas-xdelay will delay an audio band by a given delay (in seconds or
+fractions thereof).  This can be useful for tuning a sub/sat speaker
+system.  It is intended for use a dtas-player sink command as displayed
+in the synopsis.
+
+The INPUT arguments (/dev/fd/lo and /dev/fd/hi) are automatically
+changed by dtas-player to match the given file descriptors of the pipes.
+
+Both descriptors receive the same audio data, but will be split using a
+Linkwitz-Riley crossover.  The high-band (second argument) will be
+delayed by default.
+
+=head1 EXAMPLE
+
+To set this via dtas-player to delay the high frequencies by 20ms.
+
+        dtas-ctl sink ed SINKNAME \
+           command='dtas-xdelay /dev/fd/lo /dev/fd/hi 0.020'
+
+=head1 OPTIONS
+
+=over
+
+=item -x, --crossover-frequency FREQUENCY
+
+Frequency at which to set the crossover.  This defaults to 80 (Hz).
+
+=item -l, --lowpass-delay
+
+Delay the lowpass frequency instead of the highpass one.
+
+=back
+
+=head1 ENVIRONMENT
+
+=over
+
+=item SOXFMT, CHANNELS
+
+These environment variables are automatically set if
+used as a dtas-player sink
+
+=item DTAS_PLAYER_SOCK - the path to the dtas-player control socket
+
+This defaults to ~/.dtas/player.sock
+
+=item AUDIODEV, AUDIODRIVER
+
+These influence the device/driver used by L<play(1)>.
+Consult L<play(1)> for details.
+
+=item SOX_OPTS
+
+This influences options passed to L<sox(1)> or L<play(1)>
+Consult L<sox(1)> for details.
+
+=back
+
+=head1 NOTES
+
+The author of this (Eric Wong) knows little about signal processing and
+is just parroting things he's learned on the sox documentation and
+mailing list.  Corrections to the L<mailto:dtas-all@nongnu.org> mailing list
+are greatly appreciated.
+
+=head1 CONTACT
+
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
+No subscription is necessary to post to the mailing list.
+
+=head1 COPYRIGHT
+
+Copyright 2013-2016 all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
+
+=head1 SEE ALSO
+
+L<dtas-player(1)>, L<dtas-player_protocol(7)>, L<dtas-ctl(1)>,
+L<sox(1)>, L<play(1)>
diff --git a/Documentation/dtas-xdelay.txt b/Documentation/dtas-xdelay.txt
deleted file mode 100644
index 7253d1f..0000000
--- a/Documentation/dtas-xdelay.txt
+++ /dev/null
@@ -1,76 +0,0 @@
-% dtas-xdelay(1) dtas user manual
-%
-
-# NAME
-
-dtas-xdelay - play audio with a crossover delay
-
-# SYNOPSYS
-
-dtas-xdelay [OPTIONS] INPUT1 INPUT2 DELAY
-
-# DESCRIPTION
-
-dtas-xdelay will delay an audio band by a given delay (in seconds or
-fractions thereof).  This can be useful for tuning a sub/sat speaker
-system.  It is intended for use a dtas-player sink command as displayed
-in the synopsis.
-
-The INPUT arguments (/dev/fd/lo and /dev/fd/hi) are automatically
-changed by dtas-player to match the given file descriptors of the pipes.
-
-Both descriptors receive the same audio data, but will be split using a
-Linkwitz-Riley crossover.  The high-band (second argument) will be
-delayed by default.
-
-# EXAMPLE
-
-To set this via dtas-player to delay the high frequencies by 20ms.
-
-        dtas-ctl sink ed SINKNAME \
-           command='dtas-xdelay /dev/fd/lo /dev/fd/hi 0.020'
-
-# OPTIONS
-
--x, \--crossover-frequency FREQUENCY
-:   Frequency at which to set the crossover.  This defaults to 80 (Hz).
-
--l, \--lowpass-delay
-:   Delay the lowpass frequency instead of the highpass one.
-
-# ENVIRONMENT
-
-SOXFMT, CHANNELS - these environment variables are automatically set if
-used as a dtas-player sink
-
-DTAS_PLAYER_SOCK - the path to the dtas-player control socket.
-This defaults to ~/.dtas/player.sock
-
-AUDIODEV, AUDIODRIVER - these influence the device/driver used by play(1)
-Consult play(1) for details.
-
-SOX_OPTS - this influences options passed to sox(1) or play(1)
-Consult sox(1) for details.
-
-# NOTES
-
-The author of this (Eric Wong) knows little about signal processing and
-is just parroting things he's learned on the sox documentation and
-mailing list.  Corrections to the <dtas-all@nongnu.org> mailing list are
-greatly appreciated.
-
-# CONTACT
-
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
-No subscription is necessary to post to the mailing list.
-
-# COPYRIGHT
-
-Copyright 2013-2016 all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
-
-# SEE ALSO
-
-dtas-player(1), dtas-player_protocol(7), dtas-ctl(1), sox(1), play(1)
diff --git a/Documentation/update-footer.rb b/Documentation/update-footer.rb
index a6e16cb..dfc1b1a 100755
--- a/Documentation/update-footer.rb
+++ b/Documentation/update-footer.rb
@@ -3,22 +3,26 @@
 # License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
 # frozen_string_literal: true
 contact = %q{
-All feedback welcome via plain-text mail to: <dtas-all@nongnu.org>\
-Mailing list archives available at <http://80x24.org/dtas-all/> and
-<ftp://lists.gnu.org/dtas-all/>\
+All feedback welcome via plain-text mail to: L<mailto:dtas-all@nongnu.org>
+
+Mailing list archives available at L<http://80x24.org/dtas-all/>
+and L<ftp://lists.gnu.org/dtas-all/>
+
 No subscription is necessary to post to the mailing list.
 }
 
 copyright = %q{
-Copyright %s all contributors <dtas-all@nongnu.org>.\
-License: GPL-3.0+ <http://www.gnu.org/licenses/gpl-3.0.txt>
+Copyright %s all contributors L<mailto:dtas-all@nongnu.org>
+
+License: GPL-3.0+ L<http://www.gnu.org/licenses/gpl-3.0.txt>
 }
 
 ENV['TZ'] = 'UTC'
 now_year = Time.now.strftime("%Y")
 ARGV.each do |file|
-  cmd = %W(git log --reverse --pretty=format:%ad --date=short -- #{file})
-  beg_year = IO.popen(cmd, &:gets).split('-')[0]
+  cmd = %W(git log --follow -M1 --pretty=format:%ad --date=short
+           -- #{file})
+  beg_year = IO.popen(cmd, &:read).split("\n")[-1].split('-')[0]
   years = beg_year == now_year ? beg_year : "#{beg_year}-#{now_year}"
 
   File.open(file, "r+") do |fp|
@@ -27,7 +31,7 @@ ARGV.each do |file|
     sec = { state => ''.dup }
     fp.each_line do |l|
       case l
-      when /^(#.+)$/
+      when /^(=head.+)$/
         state = $1.freeze
         sections << state
         sec[state] = ''.dup
@@ -38,8 +42,8 @@ ARGV.each do |file|
 
     fp.truncate(0)
     fp.rewind
-    sec["# CONTACT"] = contact
-    sec["# COPYRIGHT"] = sprintf(copyright, years)
+    sec["=head1 CONTACT"] = contact
+    sec["=head1 COPYRIGHT"] = sprintf(copyright, years)
     while section = sections.shift
       fp.puts(section) if String === section
       blob = sec[section].sub(/\A\n+/, '').sub(/\n+\z/, '')