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

[Michael Niedermayer]

On Mon, May 03, 2010 at 08:57:46PM +0200, Stefano Sabatini wrote:
> 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.

each tool should be documented by its single manpage. Feel free to use
the c preprocessor and #include to handle duplicate stuff if theres no
better way

the verbose and detailed docs can go to html pages that can be "rendered"
into a tree of linked pages or a single monolithic html page

[...]
-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

The misfortune of the wise is better than the prosperity of the fool.
-- Epicurus
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <http://lists.mplayerhq.hu/pipermail/ffmpeg-devel/attachments/20100504/a6609fae/attachment.pgp>