From 765a7228d1815622ab0533cf2f1ffb3de04f24bc Mon Sep 17 00:00:00 2001 From: wm4 Date: Mon, 12 Dec 2016 12:03:25 +0100 Subject: 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. --- DOCS/man/mpv.rst | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'DOCS') 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 -------------------------------------------- -- cgit v1.2.3