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

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Mon Oct 15 11:13:13 2012 +0200| [7d1e003abddf18ba43be359c4d3b6194f9f2fbca] | committer: Stefano Sabatini

doc/syntax: add a "Quoting and escaping" section

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=7d1e003abddf18ba43be359c4d3b6194f9f2fbca
---

 doc/syntax.texi |   78 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 75 insertions(+), 3 deletions(-)

diff --git a/doc/syntax.texi b/doc/syntax.texi
index 169fa78..a3aabce 100644
--- a/doc/syntax.texi
+++ b/doc/syntax.texi
@@ -1,9 +1,81 @@
 @chapter Syntax
 @c man begin SYNTAX
 
-When evaluating specific formats, FFmpeg uses internal library parsing
-functions, shared by the tools. This section documents the syntax of
-some of these formats.
+This section documents the syntax and formats employed by the FFmpeg
+libraries and tools.
+
+ at anchor{quoting_and_escaping}
+ at section Quoting and escaping
+
+FFmpeg adopts the following quoting and escaping mechanism, unless
+explicitly specified. The following rules are applied:
+
+ at itemize
+ at item
+ at code{'} and @code{\} are special characters (respectively used for
+quoting and escaping). In addition to them, there might be other
+special characters depending on the specific syntax where the escaping
+and quoting are employed.
+
+ at item
+A special character is escaped by prefixing it with a '\'.
+
+ at item
+All characters enclosed between '' are included literally in the
+parsed string. The quote character @code{'} itself cannot be quoted,
+so you may need to close the quote and escape it.
+
+ at item
+Leading and trailing whitespaces, unless escaped or quoted, are
+removed from the parsed string.
+ at end itemize
+
+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 quoted or
+escaped according to the rules defined above.
+
+The tool @file{tools/ffescape} in the FFmpeg source tree can be used
+to automatically quote or escape a string in a script.
+
+ 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
+The string above contains a quote, so the @code{'} needs to be escaped
+when quoting it:
+ at example
+'Crime d'\''Amour'
+ at end example
+
+ at item
+Include leading or trailing whitespaces using quoting:
+ 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