From dc7d71fc8e3b418f73a07ab46869850279587351 Mon Sep 17 00:00:00 2001
From: wm4 <wm4@nowhere>
Date: Sat, 1 Apr 2017 21:47:19 +0200
Subject: manpage, client API: add some clarifications when commands use OSD

The APIs that run commands in a more API-like manner disable OSD and
string expansion by default.
---
 DOCS/man/input.rst | 10 +++++++---
 libmpv/client.h    |  7 +++++++
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/DOCS/man/input.rst b/DOCS/man/input.rst
index c6dc527044..6759226c6e 100644
--- a/DOCS/man/input.rst
+++ b/DOCS/man/input.rst
@@ -815,8 +815,10 @@ Input Command Prefixes
 These prefixes are placed between key name and the actual command. Multiple
 prefixes can be specified. They are separated by whitespace.
 
-``osd-auto`` (default)
-    Use the default behavior for this command.
+``osd-auto``
+    Use the default behavior for this command. This is the default for
+    ``input.conf`` commands. Some libmpv/scripting/IPC APIs do not use this as
+    default, but use ``no-osd`` instead.
 ``no-osd``
     Do not use any OSD for this command.
 ``osd-bar``
@@ -830,8 +832,10 @@ prefixes can be specified. They are separated by whitespace.
     Combine osd-bar and osd-msg.
 ``raw``
     Do not expand properties in string arguments. (Like ``"${property-name}"``.)
-``expand-properties`` (default)
+    This is the default for some libmpv/scripting/IPC APIs.
+``expand-properties``
     All string arguments are expanded as described in `Property Expansion`_.
+    This is the default for ``input.conf`` commands.
 ``repeatable``
     For some commands, keeping a key pressed doesn't run the command repeatedly.
     This prefix forces enabling key repeat in any case.
diff --git a/libmpv/client.h b/libmpv/client.h
index ee4290e22b..c6d67094d3 100644
--- a/libmpv/client.h
+++ b/libmpv/client.h
@@ -840,6 +840,9 @@ int mpv_set_option_string(mpv_handle *ctx, const char *name, const char *data);
  *
  * The commands and their parameters are documented in input.rst.
  *
+ * Does not use OSD and string expansion by default (unlike mpv_command_string()
+ * and input.conf).
+ *
  * @param[in] args NULL-terminated list of strings. Usually, the first item
  *                 is the command, and the following items are arguments.
  * @return error code
@@ -852,6 +855,8 @@ int mpv_command(mpv_handle *ctx, const char **args);
  * mpv_command_node() with the format set to MPV_FORMAT_NODE_ARRAY, and
  * every arg passed in order as MPV_FORMAT_STRING.
  *
+ * Does not use OSD and string expansion by default.
+ *
  * @param[in] args mpv_node with format set to MPV_FORMAT_NODE_ARRAY; each entry
  *                 is an argument using an arbitrary format (the format must be
  *                 compatible to the used command). Usually, the first item is
@@ -869,6 +874,8 @@ int mpv_command_node(mpv_handle *ctx, mpv_node *args, mpv_node *result);
  * Same as mpv_command, but use input.conf parsing for splitting arguments.
  * This is slightly simpler, but also more error prone, since arguments may
  * need quoting/escaping.
+ *
+ * This also has OSD and string expansion enabled by default.
  */
 int mpv_command_string(mpv_handle *ctx, const char *args);
 
-- 
cgit v1.2.3