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

[Michael Niedermayer]

On Fri, Nov 02, 2012 at 01:10:39AM +0100, Stefano Sabatini wrote:
> 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.

until someone reorders the AVOption lists
(alphabetical order for example ...)

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.

thanks

[...]

-- 
Michael     GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB

I do not agree with what you have to say, but I'll defend to the death your
right to say it. -- Voltaire
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121102/a11a5dd5/attachment.asc>