From 3083b7fbe2bc6e8dcd935b10bb7a165257c5252b Mon Sep 17 00:00:00 2001
From: Eric Wong <e@80x24.org>
Date: Mon, 18 Jan 2016 05:18:09 +0000
Subject: 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/dtas-player_sink_examples.pod | 87 +++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 Documentation/dtas-player_sink_examples.pod

(limited to 'Documentation/dtas-player_sink_examples.pod')

diff --git a/Documentation/dtas-player_sink_examples.pod b/Documentation/dtas-player_sink_examples.pod
new file mode 100644
index 0000000..da8ea76
--- /dev/null
+++ b/Documentation/dtas-player_sink_examples.pod
@@ -0,0 +1,87 @@
+% dtas-player_sink_examples(7) dtas user manual
+
+=head1 NAME
+
+dtas-player_sink_examples - sink examples for dtas-player
+
+=head1 SYNOPSIS
+
+dtas-ctl sink ed SINKNAME command='...'
+
+dtas-sinkedit SINKNAME
+
+=head1 EXAMPLES
+
+=head2 Streaming Ogg-Vorbis to Icecast
+
+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.
+
+    # set HOST/PORT/PASS via env or directly in the command
+    ---
+    name: oggfwd
+    command: sox $SOXFMT - -t ogg - | oggfwd $HOST $PORT $PASS /dtas.ogg
+
+=head2 Stream to a remote host via ssh
+
+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
+    # indented with by spaces
+    ---
+    name: ssh-remote
+    command: sox $SOXFMT - -t ogg - |
+      ssh $HOST env AUDIODEV=... play -q -t ogg -
+
+    # Note the use of env(1), as the "env" parameter for the sink may not be
+    # passed via ssh to the remote $HOST depending on the ssh_config(5)
+    # configuration.
+
+If you have a fast connection, there is no need to encode using
+Ogg-Vorbis.  Alternatively, you may also use "flac" instead of "ogg" in
+the above Ogg-Vorbis example.
+
+    ---
+    name: ssh-remote
+    command: ssh $HOST env AUDIODEV=... play -q $SOXFMT -
+
+=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 L<dtas-player_protocol(7)>.
+
+    $ dtas-ctl sink ed dumper command='sox $SOXFMT - /tmp/dump.sox'
+
+Non-"default" sinks are not active by default, but may be made active.
+
+    $ dtas-ctl sink ed dumper active=true
+
+Changing it again to "active=false" will deactivate the sink.
+
+=head2 Apply a short delay to low frequencies to improve time-alignment
+
+See L<dtas-xdelay(1)>.
+
+=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-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)>
-- 
cgit v1.2.3-24-ge0c7