[FFmpeg-devel] [PATCH] doc/encoders: Add a note for x264 options that use colon

[Stefano Sabatini]

On date Sunday 2012-11-25 21:40:33 +0400, Ivan Pozdeev encoded:
> On Sunday, November 25, 2012, 7:20:31 PM, Stefano wrote:
> > On date Sunday 2012-11-25 06:55:25 +0400, Ivan Pozdeev encoded:
> >> fef0b37152291254cb4d0141a266f3e31279c6e9
> >>  doc/encoders.texi |    3 +++
> >>  1 files changed, 3 insertions(+), 0 deletions(-)
> >> 
> >> diff --git a/doc/encoders.texi b/doc/encoders.texi
> >> index c37f256..9c7dec1 100644
> >> --- a/doc/encoders.texi
> >> +++ b/doc/encoders.texi
> >> @@ -627,6 +627,9 @@ For example to specify libx264 encoding options with @command{ffmpeg}:
> >>  ffmpeg -i foo.mpg -vcodec libx264 -x264opts keyint=123:min-keyint=20 -an out.mkv
> >>  @end example
> >>  
> 
> >> +For @var{filter} and @var{psy-rd} options that use ":" themselves, use "," instead.
> >> +They accept it as well since long ago but this is kept undocumented for some reason.
> >> +
> 
> > The context of this sentence is not very clear. I'd put the sentence
> > just below the x264opts entry, something like:
> 
> > @item x264opts @var{options}
> > Allow to set any x264 option, see x264 --fullhelp for a list.
> 
> > @var{options} is a list of @var{key}=@var{value} couples separated by
> > ":". For @var{filter} and @var{psy-rd} options that use ":"
> > themselves, use "," instead. They accept it as well since long ago but this
> > is kept undocumented for some reason.
> 
> This placement makes it somewhat unclear as to which colons to replace with
> commas :^). Let's consider this phrasing:
> 
> "... In @var{filter} and @var{psy-rd} options that use ":" as a
> separator themselves, use "," instead. ..."

LGTM, please spare me some time and update the patch.

> 
> 
> > ...
> 
> > Alternatively we may consider escaping as another possibly safer
> > alternative. Also updating x264 upstream documentation may be useful.
> 
> Does it HAVE an official documentation? doc/ in its sources has nothing
> and all I can see on the Web is
> http://mewiki.project357.com/wiki/X264_Settings which appears to be
> unofficial: the site is devoted to another piece of software, MeGUI.
> 

> Escaped character handling would add complexity that I consider
> unnecessary in this perticular case.

Well we have already de-escaping code for it, so adding the feature
would be relatively painless (and won't break backward compatibility).

> There's one parameter though, 'cqm', that can be a file name so any
> choice for a separator would potentially trouble it. Despite this, I
> suggest to leave it alone until someone has real trouble with it
> in accordance with YAGNI principle since this option seems to be
> very rarely needed.

The problem is that it applies when you're the only user, but as a
developer you don't know what others may need, and if there is a
limitation in the program it will hit someone soon or later.
-- 
FFmpeg = Fostering & Frenzy Miracolous Programmable Evanescent Gadget