From 65074ec1f074d22101b4c8bd95eb4a0354401246 Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Thu, 27 Sep 2012 03:20:12 +0200
Subject: manpage: document input.conf related things

This directly corresponds to DOCS/OUTDATED-tech/slave.txt.

Changes from the recent commits are included too.
---
 DOCS/man/en/changes.rst |  45 +++++--
 DOCS/man/en/input.rst   | 303 ++++++++++++++++++++++++++++++++++++++++++++++++
 DOCS/man/en/mplayer.rst |   2 +
 DOCS/man/en/options.rst |  34 ++++--
 4 files changed, 367 insertions(+), 17 deletions(-)
 create mode 100644 DOCS/man/en/input.rst

(limited to 'DOCS/man')

diff --git a/DOCS/man/en/changes.rst b/DOCS/man/en/changes.rst
index 11b7242d1a..de56621278 100644
--- a/DOCS/man/en/changes.rst
+++ b/DOCS/man/en/changes.rst
@@ -106,15 +106,42 @@ Command line switches
 input.conf and slave commands
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Table of renamed slave commands:
-
-    =================================== ===================================
-    Old                                 New
-    =================================== ===================================
-    pt_step 1 b                         playlist_next b
-    pt_step -1 b                        playlist_prev b
-    pt_clear                            playlist_clear
-    =================================== ===================================
+* Table of renamed input commands:
+
+    This lists only commands that are not always gracefully handled by the
+    internal legacy translation layer. If an input.conf contains any legacy
+    commands, they will be displayed with ``-v`` when it is loaded, and show
+    and the replacement commands.
+
+    Properties containing ``_`` to separate words use ``-`` instead.
+
+    +--------------------------------+----------------------------------------+
+    | Old                            | New                                    |
+    +================================+========================================+
+    | pt_step 1 [0|1]                | playlist_next [weak|force]             |
+    |                                | (translation layer can't deal with     |
+    |                                | whitespace)                            |
+    +--------------------------------+----------------------------------------+
+    | pt_step -1 [0|1]               | playlist_prev [weak|force] (same)      |
+    +--------------------------------+----------------------------------------+
+    | switch_ratio [<ratio>]         | set aspect <ratio>                     |
+    |                                | set aspect 0 (to reset aspect)         |
+    +--------------------------------+----------------------------------------+
+    | step_property_osd <prop> <step>| cycle <prop> <step> (wraps),           |
+    | <dir>                          | add <prop> <step> (clamps).            |
+    |                                | <dir> parameter unsupported. Use       |
+    |                                | a negative step instead.               |
+    +--------------------------------+----------------------------------------+
+    | step_property <prop> <step>    | Prefix cycle or add with no-osd:       |
+    | <dur>                          | no-osd cycle <prop> <step>             |
+    +--------------------------------+----------------------------------------+
+    | osd_show_property_text <text>  | show_text <text>                       |
+    |                                | The property expansion format string   |
+    |                                | syntax slightly changed.               |
+    +--------------------------------+----------------------------------------+
+    | osd_show_text                  | Now does the same as                   |
+    |                                | osd_show_property_text.                |
+    +--------------------------------+----------------------------------------+
 
 Other
 ~~~~~
diff --git a/DOCS/man/en/input.rst b/DOCS/man/en/input.rst
new file mode 100644
index 0000000000..ab392a5696
--- /dev/null
+++ b/DOCS/man/en/input.rst
@@ -0,0 +1,303 @@
+.. _input:
+
+INPUT.CONF
+==========
+
+The input.conf file consists of a list of key bindings, for example:
+
+| s screenshot      # take a screenshot with the s key
+
+Each line maps a key to an input command. Keys are specified with their literal
+value (upper case if combined with ``Shift``), or a name for special keys. For
+example, ``a`` maps to the ``a`` key without shift, and ``A`` maps to ``a``
+with shift.
+
+A list of special keys can be obtained with
+
+| **mplayer** --input=keylist
+
+In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``:
+
+| ctrl+q quit
+
+General input command syntax
+----------------------------
+
+`[Shift+][Ctrl+][Alt+][Meta+]<key> [<prefix>] <command> (<argument>)*`
+
+Newlines always start a new binding. ``#`` starts a comment (outside of quoted
+string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used.
+
+<key> is either the literal character the key produces (ASCII or unicode
+character), or a symbol name.
+
+Arguments are separated by whitespace. This applies even to string arguments.
+For this reason, string arguments should be quoted with ``"``. Inside quotes,
+C style escaping can be used.
+
+Optional arguments can be skipped with ``-``.
+
+List of input commands
+----------------------
+
+ignore
+    Use this to "block" keys that should be unbound, and do nothing. Useful for
+    disabling default bindings, without disabling all bindings with
+    ``--input=default-bindings=no``.
+
+seek <seconds> [relative|absolute|absolute-percent] [default-precise|exact|keyframes]
+    Change the playback position. By default, seeks by a relative amount of
+    seconds.
+
+    The second argument sets the seek mode:
+
+    relative (default)
+        Seek relative to current position (a negative value seeks backwards).
+    absolute
+        Seek to a given time.
+    absolute-percent
+        Seek to agiven percent position.
+
+    The third argument defines how exact the seek is:
+
+    default-precise (default)
+        Follow the default behavior as set by ``--hr-seek``, which by default
+        does imprecise seeks (like ``keyframes``).
+    exact
+        Always do exact/hr/precise seeks (slow).
+    keyframes
+        Always restart playback at keyframe boundaries (fast).
+
+frame_step
+    Basically seek forward by one frame. Actually this plays one frame, then
+    pauses again.
+
+set <property> "<value>"
+    Set the given property to the given value.
+
+add <property> [<value>]
+    Add the given value to the property. On overflow or underflow, clamp the
+    property to the maximum. If <value> is omitted, assume ``1``.
+
+cycle <property> [<value>]
+    Cycle the given property. Negative values cycle the property backwards. On
+    overflow, set the property back to the minimum, on underflow set it to the
+    maximum. If <value> is omitted, assume ``1``.
+
+speed_mult <value>
+    Multiply the ``speed`` property by the given value.
+
+screenshot [single|each-frame] [video|window]
+    Take a screenshot.
+
+    First argument:
+
+    <single> (default)
+        Take a single screenshot.
+    <each-frame>
+        Take a screenshot each frame. Issue this command again to stop taking
+        screenshots.
+
+    Second argument:
+
+    <video> (default)
+        Save the video image, in its original resolution. Typically without
+        OSD or subtitles, but the exact behavior depends on the selected video
+        output.
+    <window>
+        Save the contents of the mplayer window. Typically scaled, with OSD and
+        subtitles. The exact behavior depends on the selected video output, and
+        if not support is available, this will act like ``video``.
+
+playlist_next [weak|force]
+    Go to the next entry on the playlist.
+
+    weak (default)
+        If the last file on the playlist is currently played, do nothing.
+    force
+        Terminate playback if there are no more files on the playlist.
+
+playlist_prev [weak|force]
+    Go to the previous entry on the playlist.
+
+    weak (default)
+        If the first file on the playlist is currently played, do nothing.
+    force
+        Terminate playback if the first file is being played.
+
+loadfile "<file>" [replace|append]
+    Load the given file and play it.
+
+    Second argument:
+
+    <replace> (default)
+        Stop playback of the current file, and play the new file immediately.
+    <append>
+        Append the file to the playlist.
+
+loadlist "<playlist>" [replace|append]
+    Load the given playlist file (like ``--playlist``).
+
+playlist_clear
+    Clear the playlist, except the currently played file.
+
+run "<command>"
+    Run the given command with ``/bin/sh -c``. The string is expanded like in
+    ``--playing-msg`` before
+
+quit [<code>]
+    Exit the player using the given exit code.
+
+sub_load "<file>"
+    Load the given subtitle file. It's not selected as current subtitle after
+    loading.
+
+sub_step <skip>
+    Change subtitle timing such, that the subtitle event after the next <skip>
+    subtitle events is displayed. <skip> can be negative to step back.
+
+osd [<level>]
+    Toggle OSD level. If <level> is specified, set the OSD mode
+    (see ``--osd-level`` for valid values).
+
+show_text "<string>" [<duration>] [<level>]
+    Show text on the OSD. The string can contain properties, which are expanded
+    like in ``--playing-msg``. This can be used to show playback time, filename,
+    and so on.
+
+    <duration> is the time in ms to show the message. By default, it uses the
+    same value as ``--osd-duration``.
+
+    <level> is the minimum OSD level to show the text (see ``--osd-level``).
+
+show_progress
+    Show the progress bar, the elapsed time and the total duration of the file
+    on the OSD.
+
+show_chapters
+    Show a list of chapters on the OSD.
+
+show_tracks
+    Show a list of video/audio/subtitle tracks on the OSD.
+
+
+
+Undocumented properties: tv_start_scan, tv_step_channel, tv_step_norm,
+tv_step_chanlist, tv_set_channel, tv_last_channel, tv_set_freq, tv_step_freq,
+tv_set_norm, dvb_set_channel, radio_step_channel, radio_set_channel,
+radio_set_freq, radio_step_freq (all of these should be replaced by properties),
+edl_mark, stop (questionable use), get_property (?), af_switch, af_add, af_del,
+af_clr, af_cmdline, vo_cmdline (experimental).
+
+Input command prefixes
+----------------------
+
+osd-auto (default)
+    Use the default behavior for this command.
+no-osd
+    Do not use any OSD for this command.
+osd-bar
+    If possible, show a bar with this command. Seek commands will show the
+    progress bar, property changing commands may show the newly set value.
+osd-msg
+    If possible, show an OSD message with this command. The seek command shows
+    the current playback time (like ``show_progress``), property changing
+    commands show the newly set value as text.
+osd-msg-bar
+    Combine osd-bar and osd-msg.
+
+
+
+All of these are still overridden by the global ``--osd-level`` settings.
+
+Undocumented prefixes: pausing, pausing_keep, pausing_toggle,
+pausing_keep_force. (Should these be made official?)
+
+Properties
+----------
+
+Properties are used to set mplayer options during runtime, or to query arbitrary
+information. They can be manipulated with the ``set``/``add``/``cycle``
+commands, and retrieved with ``show_text``, or anything else that uses property
+expansion. (See ``--playing-msg`` how properties are expanded.)
+
+``W`` indicates whether the property is generally writeable. If an option
+is referenced, the property should take/return exactly the same values as the
+option.
+
+=========================== = ==================================================
+Name                        W Comment
+=========================== = ==================================================
+osd-level                   x see ``--osd-level``
+loop                        x see ``--loop``
+speed                       x see ``--speed``
+filename                      currently played file (path stripped)
+path                          currently played file (full path)
+demuxer
+stream-pos                  x byte position in source stream
+stream-start                  start byte offset in source stream
+stream-end                    end position in bytes in source stream
+stream-length                 length in bytes (${stream-end} - ${stream-start})
+stream-time-pos             x time position in source stream (also see time-pos)
+length                        length of the current file in seconds
+percent-pos                 x position in current file (0-100)
+time-pos                    x position in current file in seconds
+chapter                     x current chapter number
+edition                     x current MKV edition number
+titles                        number of DVD titles
+chapters                      number of chapters
+editions                      number of MKV editions
+angle                         current DVD angle
+metadata                      metadata key/value pairs
+metadata/<key>                value of metedata entry <key>
+pause                       x pause status (bool)
+pts-association-mode        x see ``--pts-association-mode``
+hr-seek                     x see ``--hr-seek``
+volume                      x current volume (0-100)
+mute                        x current mute status (bool)
+audio-delay                 x see ``--audio-delay``
+audio-format                  audio format (codec tag)
+audio-codec                   audio codec selected for decoding
+audio-bitrate                 audio bitrate
+samplerate                    audio samplerate
+channels                      number of audio channels
+audio                       x current audio track (similar to ``--aid``)
+balance                     x audio channel balance
+fullscreen                  x see ``--fullscreen``
+deinterlace                 x deinterlacing, if available (bool)
+colormatrix                 x see ``--colormatrix``
+colormatrix-input-range     x see ``--colormatrix-input-range``
+colormatrix-output-range    x see ``--colormatrix-output-range``
+ontop                       x see ``--ontop``
+rootwin                     x see ``--rootwin``
+border                      x see ``--border``
+framedrop                   x see ``--framedrop``
+gamma                       x see ``--gamma``
+brightness                  x see ``--brightness``
+contrast                    x see ``--contrast``
+saturation                  x see ``--saturation``
+hue                         x see ``--hue``
+panscan                     x see ``--panscan``
+vsync                       x see ``--vsync``
+video-format                  video format (integer FourCC)
+video-codec                   video codec selected for decoding
+video-bitrate                 video bitrate
+width                         video width
+height                        video height
+fps                           FPS (may contain bogus values)
+aspect                      x video aspect
+video                       x current video track (similar to ``--vid``)
+program                     x switch TS program (write-only)
+sub                         x current subttitle track (similar to ``--sid``)
+sub-delay                   x see ``--sub-delay``
+sub-pos                     x see ``--sub-pos``
+sub-visibility              x whether current subtitle is rendered
+sub-forced-only             x see ``--sub-forced-only``
+sub-scale                   x subtitle font size multiplicator
+ass-use-margins             x see ``--ass-use-margins``
+ass-vsfilter-aspect-compat  x see ``--ass-vsfilter-aspect-compat``
+tv-brightness
+tv-contrast
+tv-saturation
+tv-hue
+=========================== = ==================================================
diff --git a/DOCS/man/en/mplayer.rst b/DOCS/man/en/mplayer.rst
index 89b03737c3..840f36f23c 100644
--- a/DOCS/man/en/mplayer.rst
+++ b/DOCS/man/en/mplayer.rst
@@ -409,6 +409,8 @@ OPTIONS
 
 .. include:: encode.rst
 
+.. include:: input.rst
+
 Taking screenshots
 ==================
 
diff --git a/DOCS/man/en/options.rst b/DOCS/man/en/options.rst
index 342626d5d2..453c8e052f 100644
--- a/DOCS/man/en/options.rst
+++ b/DOCS/man/en/options.rst
@@ -1326,15 +1326,33 @@
     See also ``--user``.
 
 --playing-msg=<string>
-    Print out a string before starting playback. The following expansions are
-    supported:
+    Print out a string before starting playback. The string is expanded for
+    properties, e.g. ``--playing-msg=file: ${filename}`` will print the string
+    ``file: `` followed by the currently played filename.
+
+    The following expansions are supported:
 
     ${NAME}
-        Expand to the value of the property ``NAME``.
-    ?(NAME:TEXT)
-        Expand ``TEXT`` only if the property ``NAME`` is available.
-    ?(!NAME:TEXT)
-        Expand ``TEXT`` only if the property ``NAME`` is not available.
+        Expands to the value of the property ``NAME``. If ``NAME`` starts with
+        ``=``, use the raw value of the property. If retrieving the property
+        fails, expand to an error string. (Use ``${NAME:}`` with a trailing
+        ``:`` to expand to an empty string instead.)
+    ${NAME:STR}
+        Expands to the value of the property ``NAME``, or ``STR`` if the
+        property can't be retrieved. ``STR`` is expanded recursively.
+    ${!NAME:STR}
+        Expands to ``STR`` (recursively) if the property ``NAME`` can't be
+        retrieved.
+    ${?NAME:STR}
+        Expands to ``STR`` (recursively) if the property ``NAME`` is available.
+    $$
+        Expands to ``$``.
+    $}
+        Expands to ``}``. (To produce this character inside rexursive
+        expansion.)
+    $>
+        Disable property expansion and special handling of ``$`` for the rest
+        of the string.
 
 --playlist=<filename>
     Play files according to a playlist file (ASX, Winamp, SMIL, or
@@ -1980,7 +1998,7 @@
     the line used for the OSD and clear it (default: ``^[[A\r^[[K``).
 
 --title
-    Set the window title. The string can contain property names.
+    Set the window title. Properties are expanded (see ``--playing-msg``).
 
 --tv=<option1:option2:...>
     This option tunes various properties of the TV capture module. For
-- 
cgit v1.2.3