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

[Stefano Sabatini]

On date Wednesday 2013-07-03 17:20:49 -0700, Timothy Gu encoded:
> 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?

Ideally there should be a texi2pod project where we all
contribute. Since the copy we (well, mostly me) hacked texi2pod a lot,
so merging them may not be easy.

Also, ideally I'd like to migrate to a more powerful toolchain, pandoc
is IMO a good candidate, the main issue (apart the missing texi
drivers) would be that it requires the presence of Haskell on the
target system.

> 
> >
> > [...]
> > > > 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.)

I prefer the form with no "-", which confuses tool users, but less the
library users, and I prefer not to rely on the somehow arbitrary tool
syntax.

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

Since we enumerate the options rather than specify the syntax, I think
just writing the option might be fine.

For both points, you will observe that the documentation is not
consistent as is (different authors from different forks and with
different reviewers).

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

Thanks.
-- 
FFmpeg = Frenzy Formidable Mere Problematic Evil Gadget