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

[Clément Bœsch]

On Sat, Nov 17, 2012 at 01:52:48PM +0100, Stefano Sabatini wrote:
> 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
> 

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.

An introduction and options list for these libs in a manpage will be more
than enough IMO, exactly like what you did with libswresample.texi
recently. And I suppose it will be the same for the other lib*.texi as
well: the API usage and examples are in the doxy and should be completed,
as well as doc/examples.

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

I'd say we should keep the man ffmpeg pretty short and redirect to
dedicated manpages instead.

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

I agree.

-- 
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/20121120/5cb6ff68/attachment.asc>