[MPlayer-DOCS] complete documentation

[Diego Biurrun]

Guillaume POIRIER writes:
> 
> Le lun 06/09/2004 à 15:55, Diego Biurrun a écrit :
> > We should finish the documentation.  Of course it is never finished,
> > but we are getting very close to having every option documented.
> 
> It's been 4 days since you wrote that mail, and nobody showed up to
> provide help... Bummer.

Yes :-(

> > * audio output drivers
> >   FIXME: Document suboptions for sdl, arts, esd, jack, nas, macosx, sgi, sun,
> >   dxr2, mpegpes, null, pcm, plugin.
> > 
> > * video output drivers
> >   FIXME: Document suboptions for x11, xover, dga, sdl, vidix, xvidix, fbdev,
> >   fbdev2, vesa, null, aa, bl, ggi, mga, xmga, syncfb, 3dfx, tdfx_vid,
> >   tdfxfb, dxr2, dxr3, mpegpes, zr, zr2, yuv4mpeg, gif89a, jpeg, pgm, png, tga.
> 
> I can't take care of all of those, but I'd like to know what I'd have to
> do if I wanted to document at least one.
> Should I just look at the corresponding file at main/libao2?
> Say, ao_pcm.c? (Just like xvid option that I took care of, were at
> main/libmpcodec/ve_xvid.c)
> ... I had a look at ao_pcm.c with no luck to find any suboptions.

Yes.  Look for uses of the ao_subdevice function.  It is defined in
libao2/audio_out.c and is used to parse suboptions.  Seems like ao_pcm
has no suboptions, so go ahead, document it ;-)

> (as a sidenote, may I to point out that it has some printf(), and I
> kinda understood that the final goal was to get rid of those as they
> won't be translated, and use mp_msg instead)

Yes, printfs should be transformed to mp_msg.

> Ok, and once I'd find a suboption, how am I supposed to know what it
> means/does? ... hope the code is explicit enough.

The simplest case is that you find no suboptions, then you only have
to remove it from the FIXME: list in the man page.  If there are
suboptions you can try to understand the code and if you have trouble
doing so, ask the authors of that code or post a message to dev-eng.
Somebody should know.  As a first step, adding suboption names and
parameters to the man page and marking them "FIXME: Document this." is
already an improvement over what we have currently, like so:

  foo
    foo audio output driver
      bar=<0-1>
        FIXME: Document this.


> > * XviD encoding options
> >   There's still a few undocumented options, some are marked FIXME.
> 
> This is now done.

And it's a big part of the work :-)

Can I get you interested in documenting some of the other encoding
options?  Now that you have finished XviD we can safely tell you that
lavc is much faster and even better ;-).  The documentation is very
terse, though, and it would benefit a lot from better documentation.
I think we should try to promote lavc a bit, it deserves to be known
better.  Good user documentation should help boost it quite a bit.

Guillaume, you've done such a good job with XviD, could you repeat
that for lavc?

Diego