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

[Alexander Strasser]

Hi,

Clément Bœsch wrote:
> On Fri, Nov 16, 2012 at 06:21:34PM +0100, Stefano Sabatini wrote:
> > On date Thursday 2012-11-01 15:03:47 +0100, Stefano Sabatini encoded:
[...]
> > > 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?
> 
> It sounds indeed better. I'm fine with ffmpeg- or ff- prefix, whichever
> you prefer. A real API documentation could be added in lib*.texi, or maybe
> just an introduction to the goal, overall usage and architecture of each
> library, and eventually where to find more information for specific API
> usages (doxy, examples, /ff*.c).

  Similar to Clément I do believe keeping the section 3 lib* man pages makes
sense. I found for example zlib(3) on my system and I do think ours convey
kind of similar information. We are missing pointers to the full API docs
though, but that should be fixed easily.

  Alexander