summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
authorwm4 <wm4@nowhere>2016-12-12 12:03:25 +0100
committerwm4 <wm4@nowhere>2016-12-12 12:10:10 +0100
commit765a7228d1815622ab0533cf2f1ffb3de04f24bc (patch)
tree20f92e8ece797715f4e0677f69867dbd9a89b51e /DOCS
parent6b6789a47a3a5d872e6016625dd8609f8c632ebc (diff)
downloadmpv-765a7228d1815622ab0533cf2f1ffb3de04f24bc.tar.bz2
mpv-765a7228d1815622ab0533cf2f1ffb3de04f24bc.tar.xz
manpage: document current and legacy option syntax better
I thought it ewas already documented, but I'm not seeing it anywhere. Maybe it did exist, but was deleted. See #3899.
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/man/mpv.rst28
1 files changed, 28 insertions, 0 deletions
diff --git a/DOCS/man/mpv.rst b/DOCS/man/mpv.rst
index e40acdcff1..aa68bee896 100644
--- a/DOCS/man/mpv.rst
+++ b/DOCS/man/mpv.rst
@@ -241,6 +241,16 @@ button 5 and button 6
USAGE
=====
+Command line arguments starting with ``-`` are interpreted as options,
+everything else as filenames or URLs. All options except *flag* options (or
+choice options which include ``yes``) require a parameter in the form
+``--option=value``.
+
+One exception is the lone ``-`` (without anything else), which means media data
+will be read from stdin. Also, ``--`` (without anything else) will make the
+player interpret all following arguments as filenames, even if they start with
+``-``. (To play a file named ``-``, you need to use ``./-``.)
+
Every *flag* option has a *no-flag* counterpart, e.g. the opposite of the
``--fs`` option is ``--no-fs``. ``--fs=yes`` is same as ``--fs``, ``--fs=no``
is the same as ``--no-fs``.
@@ -248,6 +258,24 @@ 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.
+Legacy option syntax
+--------------------
+
+The ``--option=value`` syntax is not strictly enforced, and the alternative
+legacy syntax ``-option value`` and ``--option value`` will also work. This is
+mostly for compatibility with MPlayer. Using these should be avoided. Their
+semantics can change any time in the future.
+
+For example, the alternative syntax will consider an argument following the
+option a filename. ``mpv -fs no`` will attempt to play a file named ``no``,
+because ``--fs`` is a flag option that requires no parameter. If an option
+changes and its parameter becomes optional, then a command line using the
+alternative syntax will break.
+
+Currently, the parser makes no difference whether an option starts with ``--``
+or a single ``-``. This might also change in the future, and ``--option value``
+might always interpret ``value`` as filename in order to reduce ambiguities.
+
Escaping spaces and other special characters
--------------------------------------------