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

[Timothy Gu]

On Jul 3, 2013 5:34 AM, "Stefano Sabatini" <stefasab at gmail.com> wrote:
>
[...]
> On date Tuesday 2013-07-02 08:20:43 -0700, Timothy Gu encoded:
> > 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.
>
> I did, and checked the man and HTML output (in firefox) and what I see
> is messy (check attachments). That's why I suggest to keep the syntax
> simple, to avoid to confuse the very limited tools in our toolchain.

OK I didn't expect man page output to be this ugly. Sorry for the flames.

BTW, the texi2pod tool used by us was originally from GCC, and GCC already
did many more improvements since the time we pulled it in. Should we merge
some of the new stuffs in their version?

>
> [...]
> > > 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.
>
> I dislike them all, libtwolame looks the sanest but then I'd prefer to
> keep the equivalent option on the same line, rather than (confusingly)
> at the beginning of the description.

OK then, I'll use libtwolame-format.

>
> > a {
> >     color: #2D6198;
> > }
> >
> > a:visited {
> >     color: #884488;
> > }
> >
> > #banner {
> >     background-color: white;
> >     position: relative;
> >     text-align: center;
> > }
>
> Why should I read this?

You shouldn't. I attached this from doc/ in case you are using phones or
things like that that doesn't have the ffmpeg tree.

I have 2 more questions:

1. Should I include the option prefix "-"? Something like:
@item -option
instead of
@item option?
I know that adding "-" might confuse library users, but ffmpeg.texi is
using it. So what should I use? (Either way, I will adopt this unified
behavior across all docs.)

2. Should I add the accepted argument type to @item?
Like: @item option @var{integer}
or just the option itself is fine?

As we all know, consistency in docs is really important; that's why I ask
these questions.

Timothy