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

[Stefano Sabatini]

On date Friday 2012-11-16 20:10:04 +0100, Alexander Strasser encoded:
> 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.

My planned solution at this point would be:

- ff* tools manual pages

- components manual pages: codecs, formats, devices, protocols,
  filters, bitstream filters, syntax, eval (or syntax containing eval)

- lib*.texi pages with a short library description and link/mention to
  doxygen documentation, converted relevant doxygen in the best case,
  but this could be technically difficult to achieve

I'm not sure how to deal with libswrescale and libswresample. Having a
separated ffmpeg-scaler and libswscale, and ffmpeg-resampler and
libswresample pages may be a bit overkill.

Also, should we duplicate stuff between the various documents? Right
now we have e.g. duplicated options in ffmpeg.texi and
libavcodec.texi, and duplicated filter descriptions in ffmpeg.texi and
libavfilter.texi.

My preference is to move components documentation to a dedicated
manual, remove them from the tool manual pages and from the lib*.texi
files, and keep for the moment minimal description in the lib*.texi.
-- 
FFmpeg = Formidable & Fanciful Mastering Patchable Ephemeral Gospel