summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2015-01-05 14:19:18 +0100
committerDiogo Franco (Kovensky) <diogomfranco@gmail.com>2015-01-25 17:00:09 +0900
commit392159337fe9d64c3e4c63a61cdc617543664968 (patch)
tree1de55271c2495216f281ee339e2099e56b325e48
parentfffd7e7a3a2b57eb13fda334a742ba48d0e0b612 (diff)
downloadmpv-392159337fe9d64c3e4c63a61cdc617543664968.tar.bz2
mpv-392159337fe9d64c3e4c63a61cdc617543664968.tar.xz
manpage: document details of option quoting and escaping
Makes me realize what a mess this is. I hope it can be simplified in the far future, preferably by killing the suboption parser completely.
-rw-r--r--DOCS/man/mpv.rst60
1 files changed, 56 insertions, 4 deletions
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index 595c44c59a..f66fb70166 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -235,11 +235,43 @@ is the same as ``--no-fs``.
If an option is marked as *(XXX only)*, it will only work in combination with
the *XXX* option or if *XXX* is compiled in.
-.. note::
+Escaping spaces and other special characters
+--------------------------------------------
- The suboption parser (used for example for ``--ao=pcm`` suboptions)
- supports a special kind of string-escaping intended for use with external
- GUIs.
+Keep in mind that the shell will partially parse and mangle the arguments you
+pass to mpv. For example, you might need to quote or escape options and
+filenames:
+
+ ``mpv "filename with spaces.mkv" --title="window title"``
+
+It gets more complicated if the suboption parser is involved. The suboption
+parser puts several options into a single string, and passes them to a
+component at once, instead of using multiple options on the level of the
+command line.
+
+The suboption parser can quote strings with ``"``, ``'``, and ``[...]``.
+Additionally, there is a special form of quoting with ``%n%`` described below.
+
+For example, the ``opengl`` VO can take multiple options:
+
+ ``mpv test.mkv --vo=opengl:lscale=lanczos2:icc-profile=file.icc,xv``
+
+This passed ``lscale=lanczos2`` and ``icc-profile=file.icc`` to ``opengl``,
+and also specifies ``xv`` as fallback VO. If the icc-profile path contains
+spaces or characters like ``,`` or ``:``, you need to quote them:
+
+ ``mpv '--vo=opengl:icc-profile="file with spaces.icc",xv'``
+
+Shells may actually strip some quotes from the string passed to the commandline,
+so the example quotes the string twice, ensuring that mpv recieves the ``"``
+quotes.
+
+The ``[...]`` from of quotes wraps everything between ``[`` and ``]``. It's
+useful with shells that don't interpret these characters in the middle of
+an argument (like bash).
+
+A special kind of string-escaping intended for use with external scripts and
+programs is started with ``%``.
It has the following format::
@@ -253,6 +285,15 @@ It has the following format::
``mpv --ao=pcm:file=%`expr length "$NAME"`%"$NAME" test.avi``
+Suboptions passed to the client API are also subject to escaping. Using
+``mpv_set_option_string()`` is exactly like passing ``--name=data`` to the
+command line (but without shell processing of the string). Some options
+support passing values in a more structured way instead of flat strings, and
+can avoid the suboption parsing mess. For example, ``--vf`` supports
+``MPV_FORMAT_NODE``, which let's you pass suboptions as a nested data structure
+of maps and arrays. (``--vo`` supports this in the same way, although this
+fact is undocumented.)
+
Paths
-----
@@ -340,6 +381,17 @@ setting them to *no*. Even suboptions can be specified in this way.
# Use quotes for text that can contain spaces:
status-msg="Time: ${time-pos}"
+Escaping spaces and special characters
+--------------------------------------
+
+This is done like with command line options. The shell is not involved here,
+but option values still need to be quoted as a whole if it contains certain
+characters like spaces. A config entry can be quoted with ``"`` and ``'``,
+as well as with the ``%n%`` syntax mentioned before. This is like passing
+the exact contents of the quoted string as command line option. C-style escapes
+are currently _not_ interpreted on this level, although some options to this
+manually. (This is a mess and should probably be changed at some point.)
+
Putting Command Line Options into the Configuration File
--------------------------------------------------------