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

[Timothy Gu]

On Tue, Jul 2, 2013 at 1:04 AM, Stefano Sabatini <stefasab at gmail.com> wrote:
> 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.

Exactly. That's why I use 3-column design to limit the width of the
description column, comparing to the 2-column design used in libx264
doc.

> 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?

You didn't actually did texi2html, did you? I don't want to type all
the words. The attachment is ffmpeg-codecs.html generated by
texi2html, see for yourself.

>
>> >
>> > 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.

Compare libtwolame, libx264, and my libopus, and decide.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: default.css
Type: text/css
Size: 2256 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20130702/1d6bafba/attachment.css>