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

[Stefano Sabatini]

On date Thursday 2012-11-01 22:06:25 +0100, Michael Niedermayer encoded:
> On Thu, Nov 01, 2012 at 04:40:58PM +0100, Stefano Sabatini wrote:
> > On date Thursday 2012-11-01 16:03:49 +0100, Michael Niedermayer encoded:
> > > On Thu, Nov 01, 2012 at 01:24:35PM +0100, Stefano Sabatini wrote:
> > > > The option chapter is based on the avoptions_codec.texi file.
> > > 
> > > avoptions_codec.texi is a generated file
> > 
> > Inline help has the problem that it lacks information, since it
> > usually consist, when available, of a more or less cryptic single line
> > of text. A possibility would be to add a long_help option, but I
> > suggest to follow this path for the moment while a better solution is
> > developed, having a place where to document the options is already a
> > big improvement.
> > 
> > The manual labour of keeping in synch avcodec.h/options help/manual ismultiplee
> > IMHO a minor issue, given that right now the main problem is that
> > nobody ever tried to document the various options in the first place.
> 
> please add yourself in MAINTAINERS for this file then

I'm fine with maintaining the file.

The point is that the libavcodec.texi file makes sense if we want to
perform the transition for the other libraries as well (including
libavformat, libavdevice, libavfilter, libswscale and libswresample,
not sure how to deal with libavutil, we could possibly merge there the
eval.texi and syntax.texi files).

The problem with the current options table -> texi translation:

- it is meant to be embedded in the ffmpeg manpage (mentions stream
  specifier), which is against my genericity objective

- option descriptions are lacking at best, so we'd need to create at
  least a full_help option. Even in this case, we may miss the editing
  possibility of a true editing environment (texi vs. plain text for
  the option description). Having a short description accessible to
  the program, and a full extended description in the manual seems a
  feasible approach to me, and is what I followed for documenting
  components private options.

> also can you write a script that cross checks the 2 lists against
> missing options?
> if you want to maintain the texi by hand this should make your work
> easier 

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.
-- 
FFmpeg = Fostering Frenzy Murdering Proud Extended Generator