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

[Stefano Sabatini]

On date Monday 2010-05-03 19:12:38 +0200, Michael Niedermayer encoded:
> On Sat, May 01, 2010 at 06:44:00PM +0200, Stefano Sabatini wrote:
> > Hi all,
> > 
> > in attachment a sort of experiment from mine, which allows to create a
> > man page for the FFmpeg devices.
> > 
> > The idea is to have a man page for each type of element in FFmpeg:
> > codecs
> > formats
> > devices
> > protocols
> > bitstream filters
> > filters
> 
> imho a mess
> a single manpage is easier to use and to search in it

Elements are shared amongst the ff* tools and av* libraries, so there
shouldn't be imo a privileged tool man page (man ffmpeg) to contain
all the element documentation. Alternatively we could put all element
documentation in each tool man page, but this would lead to massively
monolithic man pages and redundancy of information.

That's why I'm in favor of one page per element type. Alternatively we
could put togheter related elements, for example:

bitstream filters, codecs   -> man libavcodec  / codecs
formats, devices, protocols -> man libavformat / formats

I hope that at least is clear that per-element documentation is much
needed, this is especially true for devices and filters as each one
has a rather specific syntax.

With the system I'm proposing each element is documented in its own
man page and the user knows where to look for, currently the user has
to grep the ffmpeg man page and hope to find the syntax he's looking
for, or alternatively read the HTML documentation, since for some
(historical?) reason HTML docs have *more* content than plain man
pages.

Regards.
-- 
FFmpeg = Frightening and Fundamental Minimalistic Patchable Enlightened Goblin