commit 3083b7fbe2bc6e8dcd935b10bb7a165257c5252b (patch)
parent 0699498 doc: update-footer.rb: fix for frozen_string_literal
tree af5d87ea9a2ea161df619c2305ef951cb18d087a
author Eric Wong <e@80x24.org> 2016-01-18 05:18:09 +0000
committer Eric Wong <e@80x24.org> 2016-01-18 07:02:39 +0000
doc: convert to perlpod(1) from Markdown
perlpod(1) is already installed by default on Debian and
RedHat-based systems; and probably most modern *nixes; pandoc(1)
(and Haskell) are not.
POD also more standardized than Markdown (which flavor? :P),
especially for generating manpages. So save any potential
documentation editors some disk space by not forcing them to install
Haskell and pandoc.
Finally, I'm a mildly proficient in Perl and do not know Haskell
at all and have a better chance at reading/hacking the source if
the document generator breaks.
---
Documentation/.gitignore | 1 +
Documentation/GNUmakefile | 29 +-
Documentation/dtas-archive.pod | 74 ++++
Documentation/dtas-archive.txt | 62 ---
Documentation/dtas-console.pod | 94 +++++
Documentation/dtas-console.txt | 73 ----
Documentation/{dtas-ctl.txt => dtas-ctl.pod} | 40 +-
Documentation/dtas-cueedit.pod | 38 ++
Documentation/dtas-cueedit.txt | 36 --
Documentation/dtas-enq.pod | 43 ++
Documentation/dtas-enq.txt | 41 --
Documentation/dtas-env.pod | 75 ++++
Documentation/dtas-env.txt | 60 ---
.../{dtas-msinkctl.txt => dtas-msinkctl.pod} | 32 +-
Documentation/{dtas-player.txt => dtas-player.pod} | 67 +--
Documentation/dtas-player_effects.pod | 103 +++++
Documentation/dtas-player_effects.txt | 57 ---
Documentation/dtas-player_protocol.pod | 454 +++++++++++++++++++++
Documentation/dtas-player_protocol.txt | 326 ---------------
..._examples.txt => dtas-player_sink_examples.pod} | 46 ++-
.../{dtas-sinkedit.txt => dtas-sinkedit.pod} | 58 +--
.../{dtas-sourceedit.txt => dtas-sourceedit.pod} | 59 +--
Documentation/dtas-splitfx.pod | 271 ++++++++++++
Documentation/dtas-splitfx.txt | 188 ---------
Documentation/dtas-tl.pod | 122 ++++++
Documentation/dtas-tl.txt | 96 -----
Documentation/dtas-xdelay.pod | 96 +++++
Documentation/dtas-xdelay.txt | 76 ----
| 24 +-
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
similarity index 58%
rename from Documentation/dtas-ctl.txt
rename to 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
similarity index 60%
rename from Documentation/dtas-msinkctl.txt
rename to 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
similarity index 63%
rename from Documentation/dtas-player.txt
rename to 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
similarity index 64%
rename from Documentation/dtas-player_sink_examples.txt
rename to 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
similarity index 53%
rename from Documentation/dtas-sinkedit.txt
rename to 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
similarity index 55%
rename from Documentation/dtas-sourceedit.txt
rename to 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)
--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 @@
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 @@
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/, '')
glossary
--------
Commit objects reference one tree, and zero or more parents.
Single parent commits can typically generate a patch in
unified diff format via `git format-patch'.
Multiple parents means the commit is a merge.
Root commits have no ancestor. Note that it is
possible to have multiple root commits when merging independent histories.
Every commit references one top-level tree object.
git clone git://80x24.org/dtas.git
git clone https://80x24.org/dtas.git