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

[Stefano Sabatini]

On date Monday 2012-10-15 21:55:48 +0200, Clément Bœsch encoded:
> 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)".

Simplified, does not apply anymore (and I have no idea what "magic
section" is).
 
> > + 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=...

I don't want to create interdipendences between different manual
sections, which are a PITA to maintain and tend to get desynched,
resulting in outdated examples where you don't expect them.

Patch updated, I plan to push it soon if I read no more comments.
-- 
FFmpeg = Fiendish Fantastic Marvellous Proud Ecletic Gigant
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0004-doc-syntax-add-a-Quoting-and-escaping-section.patch
Type: text/x-diff
Size: 2849 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121028/9a7833c3/attachment.bin>