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

[Clément Bœsch]

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:
> > 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?

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).

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121116/09842aef/attachment.asc>