From 36a4923f9bd05d4c5e2e8b1765f18edf452b9251 Mon Sep 17 00:00:00 2001
From: Tanu Kaskinen <tanuk@iki.fi>
Date: Thu, 16 Apr 2020 18:27:48 +0300
Subject: [PATCH] Point to SupportedAudioFormats wiki page where appropriate

I documented the supported PCM sample formats and compressed audio
encodings in the wiki, let's add some pointers to the new documentation.
---
 man/pacat.1.xml.in             | 15 +++------------
 man/pactl.1.xml.in             | 14 +++++++++-----
 man/pulse-daemon.conf.5.xml.in | 13 +++----------
 src/pulse/format.h             |  4 ++++
 src/pulse/sample.h             |  4 ++++
 src/utils/pacat.c              |  6 +++---
 6 files changed, 26 insertions(+), 30 deletions(-)

diff --git a/man/pacat.1.xml.in b/man/pacat.1.xml.in
index bfef710d1..8fcb51d92 100644
--- a/man/pacat.1.xml.in
+++ b/man/pacat.1.xml.in
@@ -116,18 +116,9 @@ License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
       <p><opt>--format</opt><arg>=FORMAT</arg></p>
 
       <optdesc><p>Capture or play back audio with the specified sample
-      format. Specify one of <opt>u8</opt>, <opt>s16le</opt>,
-      <opt>s16be</opt>, <opt>s32le</opt>, <opt>s32be</opt>,
-      <opt>float32le</opt>, <opt>float32be</opt>, <opt>ulaw</opt>,
-      <opt>alaw</opt>, <opt>s32le</opt>, <opt>s32be</opt>,
-      <opt>s24le</opt>, <opt>s24be</opt>, <opt>s24-32le</opt>,
-      <opt>s24-32be</opt>. Depending on the endianness of the CPU the
-      formats <opt>s16ne</opt>, <opt>s16re</opt>, <opt>s32ne</opt>,
-      <opt>s32re</opt>, <opt>float32ne</opt>, <opt>float32re</opt>,
-      <opt>s32ne</opt>, <opt>s32re</opt>, <opt>s24ne</opt>,
-      <opt>s24re</opt>, <opt>s24-32ne</opt>, <opt>s24-32re</opt> (for
-      native, resp. reverse endian) are available as aliases. Defaults
-      to s16ne.</p></optdesc>
+      format. See
+      https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/
+      for supported values. Defaults to s16ne.</p></optdesc>
     </option>
 
     <option>
diff --git a/man/pactl.1.xml.in b/man/pactl.1.xml.in
index 71c2826a3..cff628f34 100644
--- a/man/pactl.1.xml.in
+++ b/man/pactl.1.xml.in
@@ -243,11 +243,15 @@ License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
 
     <option>
       <p><opt>set-sink-formats</opt> <arg>SINK</arg> <arg>FORMATS</arg></p>
-      <optdesc><p>Set the supported formats of the specified sink (identified by its numerical index) if supported by the sink.
-      <arg>FORMATS</arg> is specified as a semi-colon (;) separated list of formats in the form
-      'encoding[, key1=value1, key2=value2, ...]' (for example, AC3 at 32000, 44100 and 48000 Hz would be specified as
-      'ac3-iec61937, format.rate = "[ 32000, 44100, 48000 ]"').
-      </p></optdesc> </option>
+      <optdesc><p>Set the supported formats of the specified sink (identified
+      by its numerical index) if supported by the sink. <arg>FORMATS</arg> is
+      specified as a semi-colon (;) separated list of formats in the form
+      'encoding[, key1=value1, key2=value2, ...]' (for example, AC3 at 32000,
+      44100 and 48000 Hz would be specified as
+      'ac3-iec61937, format.rate = "[ 32000, 44100, 48000 ]"'). See
+      https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/
+      for possible encodings. </p></optdesc>
+    </option>
 
     <option>
       <p><opt>subscribe</opt></p>
diff --git a/man/pulse-daemon.conf.5.xml.in b/man/pulse-daemon.conf.5.xml.in
index 780bd189e..d76e0b31d 100644
--- a/man/pulse-daemon.conf.5.xml.in
+++ b/man/pulse-daemon.conf.5.xml.in
@@ -490,16 +490,9 @@ License along with PulseAudio; if not, see <http://www.gnu.org/licenses/>.
 
     <option>
       <p><opt>default-sample-format=</opt> The default sampling
-      format. Specify one of <opt>u8</opt>, <opt>s16le</opt>,
-      <opt>s16be</opt>, <opt>s24le</opt>, <opt>s24be</opt>,
-      <opt>s24-32le</opt>, <opt>s24-32be</opt>, <opt>s32le</opt>,
-      <opt>s32be</opt>, <opt>float32le</opt>, <opt>float32be</opt>,
-      <opt>ulaw</opt>, <opt>alaw</opt>. Depending on the endianness of
-      the CPU the formats <opt>s16ne</opt>, <opt>s16re</opt>,
-      <opt>s24ne</opt>, <opt>s24re</opt>, <opt>s24-32ne</opt>,
-      <opt>s24-32re</opt>, <opt>s32ne</opt>, <opt>s32re</opt>,
-      <opt>float32ne</opt>, <opt>float32re</opt> (for native,
-      resp. reverse endian) are available as aliases.</p>
+      format. See
+      https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/
+      for possible values.</p>
     </option>
 
     <option>
diff --git a/src/pulse/format.h b/src/pulse/format.h
index 82a8be7ba..5f97929c2 100644
--- a/src/pulse/format.h
+++ b/src/pulse/format.h
@@ -62,6 +62,10 @@ typedef enum pa_encoding {
     PA_ENCODING_DTSHD_IEC61937,
     /**< DTS-HD Master Audio encapsulated in IEC 61937 header/padding. \since 13.0 */
 
+    /* Remeber to update
+     * https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/
+     * when adding new encodings! */
+
     PA_ENCODING_MAX,
     /**< Valid encoding types must be less than this value */
 
diff --git a/src/pulse/sample.h b/src/pulse/sample.h
index b368fdace..35346a865 100644
--- a/src/pulse/sample.h
+++ b/src/pulse/sample.h
@@ -171,6 +171,10 @@ typedef enum pa_sample_format {
     PA_SAMPLE_S24_32BE,
     /**< Signed 24 Bit PCM in LSB of 32 Bit words, big endian. \since 0.9.15 */
 
+    /* Remeber to update
+     * https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/
+     * when adding new formats! */
+
     PA_SAMPLE_MAX,
     /**< Upper limit of valid sample types */
 
diff --git a/src/utils/pacat.c b/src/utils/pacat.c
index 275fb7c7f..4d2ecf717 100644
--- a/src/utils/pacat.c
+++ b/src/utils/pacat.c
@@ -686,9 +686,9 @@ static void help(const char *argv0) {
              "      --stream-name=NAME                How to call this stream on the server\n"
              "      --volume=VOLUME                   Specify the initial (linear) volume in range 0...65536\n"
              "      --rate=SAMPLERATE                 The sample rate in Hz (defaults to 44100)\n"
-             "      --format=SAMPLEFORMAT             The sample type, one of s16le, s16be, u8, float32le,\n"
-             "                                        float32be, ulaw, alaw, s32le, s32be, s24le, s24be,\n"
-             "                                        s24-32le, s24-32be (defaults to s16ne)\n"
+             "      --format=SAMPLEFORMAT             The sample format, see\n"
+             "                                        https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/SupportedAudioFormats/\n"
+             "                                        for possible values (defaults to s16ne)\n"
              "      --channels=CHANNELS               The number of channels, 1 for mono, 2 for stereo\n"
              "                                        (defaults to 2)\n"
              "      --channel-map=CHANNELMAP          Channel map to use instead of the default\n"