[FFmpeg-devel] [PATCH] doc/syntax: add a "Quoting and escaping" section

[Stefano Sabatini]

---
 doc/syntax.texi |   75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 74 insertions(+), 1 deletions(-)

diff --git a/doc/syntax.texi b/doc/syntax.texi
index 169fa78..7649656 100644
--- a/doc/syntax.texi
+++ b/doc/syntax.texi
@@ -3,7 +3,80 @@
 
 When evaluating specific formats, FFmpeg uses internal library parsing
 functions, shared by the tools. This section documents the syntax of
-some of these formats.
+some of these formats, and the mechanics of the quoting mechanism
+adopted by FFmpeg libraries and components.
+
+ at anchor{quoting}
+ at section Quoting and escaping
+
+In some cases (e.g. when setting options), it is necessary to employ a
+mechanism in order to avoid that characters contained in the value
+string are interpreted like special characters.
+
+In order to to so, FFmpeg adopts the standard quoting and escaping
+mechanisms. The following rules are applied:
+
+ at itemize
+ at item
+ at code{'} is a special character (used for quoting).
+
+ at item
+A special character is escaped by prefixing it with a '\', outside a
+quoting context.
+
+ at item
+All characters enclosed between '' are included literally in the
+parsed string.
+
+ at item
+Leading and trailing whitespaces, unless escaped or quoted, are
+removed from the parsed string.
+ at end itemize
+
+Note that depending on the context, other characters are treated as
+special (e.g. @code{:} may be used to separate options), and thus
+should be quoted/escaped accordingly.
+
+Note that there is no way to specify a @code{'} within a quoted
+string, so the only way to specify a string containing a literal
+ at code{'} is to use the escaping mechanism.
+
+Note that you may need to add a second level of escaping when using
+the command line or a script, which depends on the syntax of the
+adopted shell language.
+
+The function @code{av_get_token} defined in
+ at file{libavutil/avstring.h} can be used to parse a token according to
+the quoting and escaping rules defined above.
+
+ at subsection Examples
+
+ at itemize
+ at item
+Escape the string @code{Crime d'Amour} containing the @code{'} special
+character:
+ at example
+Crime d\'Amour
+ at end example
+
+ at item
+To include leading or trailing whitespaces, use the quoting mechanism:
+ at example
+'  this string starts and ends with whitespaces   '
+ at end example
+
+ at item
+Escaping and quoting can be mixed together:
+ at example
+' The string '\'string\'' is a string '
+ at end example
+
+ at item
+To include a literal @code{\} you can use either escaping or quoting:
+ at example
+'c:\foo' can be written as c:\\foo
+ at end example
+ at end itemize
 
 @anchor{date syntax}
 @section Date
-- 
1.7.5.4