[FFmpeg-devel] [PATCH] doc/encoders: Add libopus encoder doc

[Stefano Sabatini]

On date Monday 2013-07-01 13:24:29 -0700, Timothy Gu encoded:
> On Jul 1, 2013 7:18 AM, "Stefano Sabatini" <stefasab at gmail.com> wrote:
> >
> > On date Friday 2013-06-28 16:46:21 -0700, Timothy Gu encoded:
> > > ---
> > >  doc/encoders.texi | 74
> +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 74 insertions(+)
> > >
> > > diff --git a/doc/encoders.texi b/doc/encoders.texi
> > > index 7da6376..c3db780 100644
> > > --- a/doc/encoders.texi
> > > +++ b/doc/encoders.texi
> > > @@ -629,6 +629,80 @@ Same as 3, but with extra processing enabled -
> corresponding to the wavpack
> > >
> > >  @end table
> > >
> > > + at section libopus
> > > +
> > > +libopus Opus Interactive Audio Codec encoder wrapper.
> > > +
> > > +Requires the presence of the libopus headers and library during
> > > +configuration. You need to explicitly configure the build with
> > > + at code{--enable-libopus}.
> > > +
> > > + at subsection Option Mapping
> > > +
> > > +Most libopus options are modeled after the @command{opusenc} utility
> from
> > > +opus-tools. The following is an option mapping chart describing options
> > > +supported by the libopus wrapper, and their
> @command{opusenc}-equivalent.
> > > +
> > > + at multitable @columnfractions .15 .15 .7
> > > + at headitem FFmpeg                 @tab @command{opusenc}
> >
> > I would avoid the @columnfractions MAGIC altogether, which has a poor
> > rendering in the HTML output (and thus I'd avoid it in
> > libmp3lame/lib264 docs as well).
> 

> Okay, but you told me that you like two columns with separate options like
> this better, and now I think you were right.
> 
> http://ffmpeg.org/pipermail/ffmpeg-devel/2013-May/144286.html
> 
> Try to actually build the HTML and you will see that this renders better
> than you think. Either way I will send a separate patch to normalize all
> the behaviors.

Looking for example at the libx264 option mapping I see:

b	bitrate FFmpeg b option is expressed in bits/s, x264 bitrate in kilobits/s.
bf	bframes Maximum number of B-frames.

here it is not very clear where the second column terminates and the
description starts. The man output looks a bit better, since the
description is put on a separate line. Also what happens if the
description can't be contained in the same line?

> >
> > What I suggest instead:
> > @item b (bitrate)
> >
> > or if you prefer:
> > @item b (@emph{bitrate})
> >
> > adopting the KISS principle.
> 
> The thing I did isn't simple?
> 
> >
> >
> > > + at tab Comments
> > > +
> > > + at item @option{b}                 @tab @option{bitrate}
> >
> > @item b ...
> >
> > should be more consistent with the rest of the docs (check also HTML
> > output)
> 
> Again, now I don't want to hear "use the format other docs are using", I
> want to __change__ the format.

Consider:

@table @option
@item foo
...

@table @option
@item @option{foo}
...

The second form is not used anywhere, and is probably rendered the
same way as the first one but is more verbose, thus I prefer the first
form.

[...]
-- 
FFmpeg = Furious and Fundamentalist Multimedia Perfectionist Esoteric Guru