[FFmpeg-devel] [RFC] Better modularization and extension of docs - 2

Stefano Sabatini stefasab at gmail.com
Fri Nov 16 18:21:34 CET 2012


On date Thursday 2012-11-01 15:03:47 +0100, Stefano Sabatini encoded:
> On date Sunday 2012-09-09 11:51:39 +0200, Clément Bœsch encoded:
> > On Fri, Sep 07, 2012 at 01:55:24PM +0200, Stefano Sabatini wrote:
[...]
> > > Possible sections would be:
> > > 
> > > tools: ffmpeg/ffplay/ffprobe/ffserver
> > > protocols
> > > muxers
> > > demuxers
> > > indevs
> > > outdevs
> > > decoders
> > > encoders
> > > bitstream-filters/bsfs
> > > filters
> > > 
> > > It may made sense to merge muxers/demuxers => formats,
> > > indevs/outdevs => devices, decoders/encoders => codecs.
> > > 
> > 
> > No need to oversplit everything; so yes I think it makes more sense to
> > merge muxers and demuxers (and protocols?) into formats, decoders and
> > encoders into codecs, and indevs and outdevs into devices.
> 
> Hi,
> 
> I just sent libavcodec.texi, the big plan:
> 
> - add more pages: libavformat, libavdevice, libavfilter, libswscale,
>   libswresample.
>   The library pages should contain a possibly extensive description of the
>   various options (which so far is only covered by ffmpeg -h full or
>   the source code).
> 
> - remove library specific bits from the tool man pages, in order to
>   have more wieldly pages
> 
> For example decoders.texi and encoders.texi should be merged into
> libavcodec.texi.
> 
> The whole point of the reformatting is to get more modular
> documentation (e.g. no need to grep all the ffmpeg huge man page to
> find a filter), to provide a *place* where to document library
> specific topics (e.g. encoding quality), and where to extend the
> really sparse documentation for the various options.

I discussed this with Michael and Clement, there are some concerns
about the current implementation.

Manual section #3 is really meant for API, while we're using it for
something which is closer to "high-level library usage" (selecting
options for the various components), thus having a file named like
libfoo.texi looks a bit misleading.

A possible alternative, like I listed above: we create a section of
the manual for the various "components", for example:

ffmpeg-codecs
ffmpeg-formats
ffmpeg-protocols
ffmpeg-filters
ffmpeg-bitstream-filters
ffmpeg-syntax
ffmpeg-eval
etc.

This would still achive the objective of a better modularization, and
should also simplify reference for programmers relying on the
"high-level interface" provided by options and per-component syntax.

Opinions?
-- 
FFmpeg = Fascinating and Freak Meaningful Puritan Evil Guru


More information about the ffmpeg-devel mailing list