[FFmpeg-devel] [PATCH] documentation: Fix several documentation bugs in trac ticket #2413

[Michael Ludwig]

Derek Buitenhuis schrieb am 04.04.2013 um 15:25 (-0400):
> On 2013-04-04 1:53 PM, Stefano Sabatini wrote:
> >> >  movie=/dev/video0:f=video4linux2, scale=180:-1, setpts=PTS-STARTPTS [movie];
> >> > -[in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
> >> > +[in] setpts=PTS-STARTPTS [setpts], [setpts] [movie] overlay=16:16 [out]
> > I find this slightly more complex to understand than:
> > [in] setpts=PTS-STARTPTS, [movie] overlay=16:16 [out]
> > 
> > What's the rationale?
> 
> It's more explicit in showing which clips are where.
> 
> Easier to follow IMHO.

I also stumbled over the unlabelled (implicit) outputs and
inputs for overlay filters in the Filtering Introduction. I
agree with both of you. The implicit syntax is easier to
read once you've understood how it works; but it's confusing
as long as you haven't. So I would introduce both syntaxes
at the same time and include a comment for newbies about it.

I already posted these suggestions (for the wrong mirroring
example in the introduction) on the user list - listed in
decreasing order of explicitness:

-vf "[in] split [S1][S2]; [S2] crop=iw:ih/2:0:0, vflip [Mir]; [S1][Mir] overlay=0:H/2 [out]"
-vf "[in] split [Whole], crop=iw:ih/2:0:0, vflip [Mir]; [Whole][Mir] overlay=0:H/2 [out]"
-vf "[in] split [Whole], crop=iw:ih/2:0:0, vflip, [Whole] overlay=0:H/2 [out]"

Description: "The result will be that in output the top half
of the video is mirrored onto the bottom half."

The newbie should be explained that these three filters do
the same thing, drawing attention to the fact that …

(a) split has two outputs,
(b) overlay has two inputs,
(c) outputs and inputs may be unlabeled,
(d) unlabeled inputs (and outputs, too?) go after labeled
    inputs (and outputs?)
(e) both syntaxes are okay to use and it's a matter of
    style or taste (if that is the case).

The introductory example should be friendly to the newbie,
neither only terse and idiomatic, nor only overly verbose,
which may also confuse people. So I think it's best to
repeat the example like I did above. That provides a better
context for understanding, I think.

Michael