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

[Clément Bœsch]

On Mon, Oct 15, 2012 at 11:16:24AM +0200, Stefano Sabatini wrote:
> ---
>  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.
> +

maybe add a parenthesis with some examples (and eventually magic section
references links) like "(such as [filters] arguments)".

> + 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 '

You're sure you will generate the correct output in the man and html page
with this? (it would be a shame to have the escaping pages wrongly
escaped).

Also how about giving a real case example like an example with
"drawtext='hey ^^\' "bla"':foobar=... or something. Or maybe with a file
and movie=...

> + 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
>  

Anyway, rest LGTM

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121015/f1e64506/attachment.asc>