From 8b2c27f6c83187b0a941ffd09f08f54d50f405ba Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Sun, 3 Feb 2013 16:40:02 +0100
Subject: manpage: document option syntax variations better

---
 DOCS/man/en/changes.rst |  6 ++++--
 DOCS/man/en/mpv.rst     | 27 +++++++++++++++++++++++++--
 2 files changed, 29 insertions(+), 4 deletions(-)

(limited to 'DOCS')

diff --git a/DOCS/man/en/changes.rst b/DOCS/man/en/changes.rst
index eb3f4d0d91..892b3f0af9 100644
--- a/DOCS/man/en/changes.rst
+++ b/DOCS/man/en/changes.rst
@@ -120,10 +120,12 @@ Command line switches
     -vobsub                             --sub (pass the .idx file)
     -ass-bottom-margin                  --vf=sub=bottom:top
     -vc ffh264vdpau (etc.)              --hwdec=vdpau
-    -x, -y                              --geometry + --no-keepaspect
-    -xy                                 --autofit
+    -x W, -y H                          --geometry=WxH + --no-keepaspect
+    -xy W                               --autofit=W
     =================================== ===================================
 
+*NOTE*: ``-opt val`` becomes ``--opt=val``.
+
 input.conf and slave commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/DOCS/man/en/mpv.rst b/DOCS/man/en/mpv.rst
index d8fa642546..60f8d0cabc 100644
--- a/DOCS/man/en/mpv.rst
+++ b/DOCS/man/en/mpv.rst
@@ -279,11 +279,34 @@ the *XXX* option or if *XXX* is compiled in.
   GUIs.
 | It has the following format:
 | %n%string\_of\_length\_n
+
 | *EXAMPLES*:
-| `mpv --ao pcm:file=%10%C:test.wav test.avi`
+| `mpv --ao=pcm:file=%10%C:test.wav test.avi`
 | Or in a script:
-| `mpv --ao pcm:file=%\`expr length "$NAME"\`%"$NAME" test.avi`
+| `mpv --ao=pcm:file=%\`expr length "$NAME"\`%"$NAME" test.avi`
+
+Single dash versus double dash options
+--------------------------------------
+
+There are actually two option syntaxes: one which uses a single dash (``-opt``),
+and one with double dashes (``--opt``). The double dash syntax always requires
+a ``=`` to separate option name and value, while single dash options use a
+space.
+
+
+| Both of these examples pass the value `pcm:file=test.wav` to the `ao` option:
+| `mpv -ao pcm:file=test.wav`
+| `mpv --ao=pcm:file=test.wav`
+
+| This passes the empty string to `ao`, while `pcm:file=test.wav` is interpreted
+  as filename (common mistake):
+| `mpv --ao pcm:file=test.wav`
+
+It's best to stick to one syntax to avoid usage errors. The double dash syntax
+is preferred, and used throughout the manpage.
 
+*NOTE*: the differences between these syntaxes might be removed in the future.
+However, this has not happened yet.
 
 Per-file options
 ----------------
-- 
cgit v1.2.3