Quoting Stefano Sabatini (2024-01-20 12:32:42)
> 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 moved it to a new paragraph.
> > 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.
I don't, neither does most literature I can recall. Typically you first
present a thing, then explain its structure. Explaning the structure of
something the reader has not seen yet is backwards, unnatural, and hard
to understand.
>
> 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.
I disagree. Examples should focus on whatever can be usefully explained
with an example.
--
Anton Khirnov
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
