[FFmpeg-devel] [PATCH] doc: add ffmpeg-bitstream-filters.texi file

[Stefano Sabatini]

On date Wednesday 2012-11-28 11:30:28 +0100, Nicolas George encoded:
> Le septidi 7 frimaire, an CCXXI, Stefano Sabatini a écrit :
> > But still bitstream filters API and functionality is embedded in
> > libavcodec, so users *should* be aware of that in case they need them
> > 
> > Also people looking for bitstream filters are ubergeek users anyway,
> > and are able to figure it out themselves,
> 
> That makes sense.
> 
> >					    while "normal" users finding
> > bitstream filters in the "media" filters manual will easily get
> > confused.
> 
> That is likely. But maybe the occasion will make them realize that bitstream
> filters exist and can solve their problems. Well, this obscure part can be
> moved later anyway, so please proceed as you see fit.

Thanks, pushed for now.

> 
> But let me check something, because you were not part of that discussion. I
> think that at some point we should add to lavfi support for filtering
> packets of data. When that happens, bitstream filters will just be
> data->data filters (and codecs data->audio or video->data, etc. filters).
> Do you agree?

I agree, but I can't state how long and painful that would be. My long
term priority for libavfilter (apart dynamic reconfiguration) is to
add support to subtitles filtering.

> 
> > There is @ifset, but I'm not sure it is properly suppported in
> > texi2pod.pl. I'll test it soon as I want to understand if it is
> 
> A quick look at the code shows that it is at least supposed to be supported.
> Converting config.h into config.texi should be quite easy. Then surrounding
> the documentation of each component by "@ifset CONFIG_COMPONENT" ... "@end
> ifset" should do the trick.
> 
> Do you think it would be a good idea?

But I don't want to overdesign things. Also, even if you don't have a
component installed (e.g. no drawtext because no --enable-freetype) I
think it would be useful to find drawtext documented, so the user
knows that she can enable it.

For the moment in my branch I'm generating a doc/config.texi, that I
include at the begin of each manual, and which defines @set
doc-monolithic if enabled during configuration (and there are a few
other layout issues to be fixed as well).

> 
> (I do not want to go at it straight away, because it is very likely to cause
> a lot of rebase conflicts with your work.)

@ifset works but with a glitch which I'm trying to fix (@ifset is only
recognized inside sections, so there is no way to include chapters
conditionally, texi2html works just fine).
 
> > possible to still compile Huge Wall of Text manuals, for users
> > preferring that.
> 
> A simple meta-man-page should be enough:
> 
> .TH "FFMPEG-ALL" "1" "November 28, 2013" "ffmpeg git"
> .SH "NAME"
> ffmpeg-all \- the FFmpeg full man page
> .so man1/ffmpeg-codecs.1
> .so man1/ffmpeg-devices.1
> .so man1/ffmpeg-filters.1
> .so man1/ffmpeg-formats.1
> .so man1/ffmpeg-protocols.1
> .so man1/ffmpeg-resampler.1
> .so man1/ffmpeg-scaler.1
> .so man1/ffmpeg-utils.1
> .so man1/ffmpeg.1
> .so man1/ffplay.1
> .so man1/ffprobe.1
> .so man1/ffserver.1
> 
> should work, provided the man pages are installed (not in the source tree).

What I dislike of the approach is that it is man-specific, while a
more texinfo-based approach would serve both man and HTML docs.
-- 
FFmpeg = Fancy & Fast Mere Puritan Ecstatic Game