[FFmpeg-devel] [PATCH 7/8] fftools/ffmpeg_demux: implement -bsf for input

[Stefano Sabatini]

On date Wednesday 2024-01-17 10:02:31 +0100, Anton Khirnov wrote:
> Quoting Stefano Sabatini (2024-01-06 13:12:19)
> > 
> > This looks spurious, since this suggests the example is about the
> > listing, and it's applying a weird order of example/explanation
> > (rather than the opposite).

Use the @code{-bsfs} option to get the list of bitstream filters. E.g.
@example
...

The problem here is that "E.g." is placed close to a statement about
the listing, therefore it might sound like the example is about the
listing (which is not).

> I see nothing weird about this order, it's the standard way it is done
> in most literature I encounter. I find the reverse order you're
> suggesting far more weird and unnatural.

When you present an example you usually start with an explanation
(what it does) and then present the command, not the other way around.

Also the following:
--------------------------------------
ffmpeg -bsf:v h264_mp4toannexb -i h264.mp4 -c:v copy -an out.h264
@end example
applies the @code{h264_mp4toannexb} bitstream filter (which converts
MP4-encapsulated H.264 stream to Annex B) to the @emph{input} video stream.

On the other hand,
@example
ffmpeg -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
@end example
applies the @code{mov2textsub} bitstream filter (which extracts text from MOV
subtitles) to the @emph{output} subtitle stream. Note, however, that since both
examples use @code{-c copy}, it matters little whether the filters are applied
on input or output - that would change if transcoding was hapenning.
---------------------------------------

this makes the reader need to correlate the two examples to figure
them out, that's why I reworked the presentation in my suggestion as a
more linear sequence of presentation/command/presentation/command.

In general examples should focus on how a task can be done, not on the
explanation of the command itself.