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

[Alexander Strasser]

Stefano Sabatini wrote:
> On date Tuesday 2012-11-20 22:55:46 +0100, Clément Bœsch encoded:
> > On Sat, Nov 17, 2012 at 01:52:48PM +0100, Stefano Sabatini wrote:
> [...]
> > > 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
> > > 
> > 
> > Sounds pretty sane overall, except for the syntax dedicated manpage for
> > which I'm a bit uncomfortable.
> > 
> > > 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.
> > > 
> > 
> > For users, these libraries are only accessible through the filters. Usage
> > will be documented there.
> 
> I dislike the idea of documenting scaler and resampler options in
> filter documentation. There may be other internal components in the
> future (or a third party app) relying on those options. Also note that
> libswscale and libswresample options *are* accessible through ffmpeg.
> 
> On the other hand having libswscale/resample.texi and
> ffmpeg-scaler/resampler.texi seems a bit overkill, but I think it is
> the more consistent scheme.

  IMHO it makes sense to have lswr options documented in lswr docs. As
far as ffmpeg and filters are concerned I would prefer to only document
the "deltas" in ffmpeg/filters docs. E.g. the filter is a pretty straight
forward wrapper IIRC. So it should be easy to explain how to use the
lswr docs to parametrize the filter. OTOH duplication should still be
allowed to a limited extend if it helps to understand how things are
mapped and of course in examples.

> [...]

  Alexander