From 8a7986c3bf13415790932cf1f27c3a1f8144a01a Mon Sep 17 00:00:00 2001
From: Max Kellermann <max@musicpd.org>
Date: Tue, 10 Nov 2020 15:48:47 +0100
Subject: [PATCH] doc/plugins.rst: add DSD spec links

---
 doc/plugins.rst | 12 ++++++++++--
 doc/user.rst    | 12 ++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/doc/plugins.rst b/doc/plugins.rst
index 06fe714c1..96ce259b7 100644
--- a/doc/plugins.rst
+++ b/doc/plugins.rst
@@ -378,10 +378,14 @@ flac
 
 Decodes FLAC files using libFLAC.
 
+.. _decoder_dsdiff:
+
 dsdiff
 ------
 
-Decodes DFF files containing DSDIFF data (e.g. SACD rips).
+Decodes DSDIFF (`Direct Stream Digital Interchange File Format
+<http://www.sonicstudio.com/pdf/dsd/DSDIFF_1.5_Spec.pdf>`_) files
+(:file:`*.dff`).  These contain :ref:`DSD <dsd>` instead of PCM.
 
 .. list-table::
    :widths: 20 80
@@ -392,10 +396,14 @@ Decodes DFF files containing DSDIFF data (e.g. SACD rips).
    * - **lsbitfirst yes|no**
      - Decode the least significant bit first. Default is no.
 
+.. _decoder_dsf:
+
 dsf
 ---
 
-Decodes DSF files containing DSDIFF data (e.g. SACD rips).
+Decodes DSF
+(<https://dsd-guide.com/sites/default/files/white-papers/DSFFileFormatSpec_E.pdf>)
+files (:file:`*.dsf`).  These contain :ref:`DSD <dsd>` instead of PCM.
 
 fluidsynth
 ----------
diff --git a/doc/user.rst b/doc/user.rst
index abd7c7b1f..694ce0cc5 100644
--- a/doc/user.rst
+++ b/doc/user.rst
@@ -1032,12 +1032,20 @@ Check list for bit-perfect playback:
   :code:`format`, :ref:`audio_output_format <audio_output_format>`).
 * Verify that you are really doing bit-perfect playback using :program:`MPD`'s verbose log and :file:`/proc/asound/card*/pcm*p/sub*/hw_params`. Some DACs can also indicate the audio format.
 
+.. _dsd:
+
 Direct Stream Digital (DSD)
 ---------------------------
 
-DSD (`Direct Stream Digital <https://en.wikipedia.org/wiki/Direct_Stream_Digital>`_) is a digital format that stores audio as a sequence of single-bit values at a very high sampling rate.
+DSD (`Direct Stream Digital
+<https://en.wikipedia.org/wiki/Direct_Stream_Digital>`_) is a digital
+format that stores audio as a sequence of single-bit values at a very
+high sampling rate.  It is the sample format used on `Super Audio CDs
+<https://en.wikipedia.org/wiki/Super_Audio_CD>`_.
 
-:program:`MPD` understands the file formats dff and dsf. There are three ways to play back DSD:
+:program:`MPD` understands the file formats :ref:`DSDIFF
+<decoder_dsdiff>` and :ref:`DSF <decoder_dsf>`.  There are three ways
+to play back DSD:
 
 * Native DSD playback. Requires ALSA 1.0.27.1 or later, a sound driver/chip that supports DSD and of course a DAC that supports DSD.