[FFmpeg-devel] [PATCH] doc: add libavcodec.texi first version

[Stefano Sabatini]

On date Friday 2012-11-02 02:28:09 +0100, Michael Niedermayer encoded:
> On Fri, Nov 02, 2012 at 01:10:39AM +0100, Stefano Sabatini wrote:
[...]
> > Also I believe that the big part of the work consists into the
> > documentation task itself, rather than in the manual synching, which
> > is relatively trivial. I could write a script, but I'm sure how much
> > could help, for the moment I'd only strive to keep the same order
> > between the options in the .h file and the texi file, it's not like we
> > touch so much the help text very often anyway.
> 
> until someone reorders the AVOption lists
> (alphabetical order for example ...)

Well even in this case reordering the options in the texi should not
be hard.

> about the texi, i think we are missing a obvious opertunity here.
> And that is that documentation should be editable by the community,
> others like burek have suggested this also multiple times. And i
> think it makes a lot of sense for new files like this to be rather
> wiki than texi.

Please let me repeat again why I strongly object this, reference
documentation is different from user contributed documentation, you
don't want to dump a wiki (updated to which FFmpeg version?) or need
an Internet connection to read the reference, and you don't want
Random J. User to edit the options description with no review, for the
same reasons you don't want a random user to edit the reference specs
of your microwaves oven.

User contributed docs have a different target and objective of the
reference specification/documentation.
-- 
FFmpeg = Fiendish Fascinating Mere Problematic Enhancing Gospel