manpage: add notes when to use/not use certain AO and VO drivers

Conflicts:
	DOCS/man/en/vo.rst

2 files changed, 50 insertions, 1 deletions

diff --git a/DOCS/man/en/ao.rst b/DOCS/man/en/ao.rst
index df2c33e119..8fd3b80a60 100644
--- a/DOCS/man/en/ao.rst
+++ b/DOCS/man/en/ao.rst
@@ -18,7 +18,12 @@ normal driver parameters.
 
 .. note::
 
-    See ``--ao=help`` for a list of compiled-in audio output drivers.
+    See ``--ao=help`` for a list of compiled-in audio output drivers. The
+    driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems
+    where PulseAudio is forced. On Windows, ``--ao=wasapi`` is preferred,
+    though it might cause trouble sometimes, in which case ``--ao=dsound``
+    should be used. On BSD systems, ``--ao=oss`` or `--ao=sndio`` may work
+    (the latter being experimental). On OSX systems, use ``--ao=coreaudio``.
 
 .. admonition:: Examples
 
@@ -118,6 +123,9 @@ Available audio output drivers are:
 ``openal``
     Experimental OpenAL audio output driver
 
+    .. note:: This driver is not very useful. Playing multi-channel audio with
+              it is slow.
+
 ``pulse``
     PulseAudio audio output driver
 
@@ -130,6 +138,10 @@ Available audio output drivers are:
     PortAudio audio output driver. This works on all platforms, and has
     extensive MS Windows support.
 
+    .. note:: This driver is not very useful. It was added in the hope of
+              providing portable audio API across all platforms, but turned
+              our semi-broken and underfeatured.
+
     ``device``
         Specify the subdevice to use. Giving ``help`` as device name lists all
         devices found by PortAudio. Devices can be given as numeric values,
@@ -138,6 +150,8 @@ Available audio output drivers are:
 ``dsound`` (Windows only)
     DirectX DirectSound audio output driver
 
+    .. note:: This driver is for compatibility with old systems.
+
     ``device=<devicenum>``
         Sets the device number to use. Playing a file with ``-v`` will show a
         list of available devices.
@@ -147,6 +161,10 @@ Available audio output drivers are:
     1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set
     appropriately for your system.
 
+    .. note:: This driver is for compatibility with extremely foreign
+              environments, such as systems where none of the other drivers
+              are available.
+
     ``buflen=<length>``
         Sets the audio buffer length in seconds. Is used only as a hint by the
         sound system. Playing a file with ``-v`` will show the requested and
@@ -186,6 +204,10 @@ Available audio output drivers are:
 ``rsound``
     Audio output to an RSound daemon
 
+    .. note:: Completely useless, unless you intend to run RSound. Not to be
+              confused with RoarAudio, which is something completely
+              differently.
+
     ``host=<name/path>``
         Set the address of the server (default: localhost).  Can be either a
         network hostname for TCP connections or a Unix domain socket path
@@ -197,6 +219,8 @@ Available audio output drivers are:
 ``sndio``
     Audio output to the OpenBSD sndio sound system
 
+    .. note:: Experimental. There are known bugs and issues.
+
     (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel
     layouts.)
 
diff --git a/DOCS/man/en/vo.rst b/DOCS/man/en/vo.rst
index 8a7e8e55ff..fa9f980bab 100644
--- a/DOCS/man/en/vo.rst
+++ b/DOCS/man/en/vo.rst
@@ -20,6 +20,9 @@ normal driver parameters.
 
     See ``--vo=help`` for a list of compiled-in video output drivers.
 
+    The recommended output drivers are ``--vo=vdpau`` and ``--vo=opengl-hq``.
+    All other drivers are just for compatibility or special purposes.
+
 .. admonition:: Example
 
     ``--vo=opengl,xv,``
@@ -32,6 +35,8 @@ Available video output drivers are:
     the most compatible VO on X, but may be low-quality, and has issues with
     OSD and subtitle display.
 
+    .. note:: This driver is for compatibility with old systems.
+
     ``adaptor=<number>``
         Select a specific XVideo adaptor (check xvinfo results).
     ``port=<number>``
@@ -172,6 +177,9 @@ Available video output drivers are:
 ``direct3d_shaders`` (Windows only)
     Video output driver that uses the Direct3D interface.
 
+    .. note:: This driver is for compatibility with systems that don't provide
+              proper OpenGL drivers.
+
     ``prefer-stretchrect``
         Use ``IDirect3DDevice9::StretchRect`` over other methods if possible.
 
@@ -228,11 +236,15 @@ Available video output drivers are:
     Same as ``direct3d_shaders``, but with the options ``disable-textures``
     and ``disable-shaders`` forced.
 
+    .. note:: This driver is for compatibility with old systems.
+
 ``corevideo`` (Mac OS X 10.6 and later)
     Mac OS X CoreVideo video output driver. Uses the CoreVideo APIs to fill
     PixelBuffers and generate OpenGL textures from them (useful as a fallback
     for ``opengl``).
 
+    .. note:: This driver is for compatibility with old systems.
+
 ``opengl``
     OpenGL video output driver. It supports extended scaling methods, dithering
     and color management.
@@ -519,6 +531,8 @@ Available video output drivers are:
     implementation, even if you do not get any error message. Use ``glxinfo``
     or a similar tool to display the supported OpenGL extensions.
 
+    .. note:: This driver is for compatibility with old systems.
+
     ``(no-)ati-hack``
         ATI drivers may give a corrupted image when PBOs are used (when using
         ``force-pbo``). This option fixes this, at the expense of using a bit
@@ -692,6 +706,9 @@ Available video output drivers are:
     hardware acceleration. Should work on all platforms supported by SDL 2.0.
     For tuning, refer to your copy of the file ``SDL_hints.h``.
 
+    .. note:: This driver is for compatibility with systems that don't provide
+              proper graphics drivers, or which support GLES only.
+
     ``sw``
         Continue even if a software renderer is detected.
 
@@ -704,6 +721,9 @@ Available video output drivers are:
     hardware decoding to save power on laptops, or possibly preventing video
     tearing with some setups.
 
+    .. note:: This driver is for compatibility with crappy systems. You can
+              use vaapi hardware decoding with ``--vo=opengl`` too.
+
     ``scaling=<algorithm>``
         default
             Driver default (mpv default as well).
@@ -744,6 +764,8 @@ Available video output drivers are:
 ``caca``
     Color ASCII art video output driver that works on a text console.
 
+    .. note:: This driver is a joke.
+
 ``image``
     Output each frame into an image file in the current directory. Each file
     takes the frame number padded with leading zeros as name.
@@ -789,6 +811,9 @@ Available video output drivers are:
 ``wayland`` (Wayland only)
     Wayland shared memory video output as fallback for ``opengl``.
 
+    .. note:: This driver is for compatibility with systems that don't provide
+              working OpenGL drivers.
+
     ``default-format``
         Use the default RGB32 format instead of an auto-detected one.