[MPlayer-dev-eng] [PATCH] man page: Where do you want to go tommorow?

[Arpi]

Hi,

> man page: usage, options, keyboard control, etc
> html: detailed/advanced installation instructions, tutorials
> tech/: hacker's corner

yes!

html could cover topics like
- where to download driver for my vga/sound/etc card - what do i need,
  vo drivers (video.html)
- performance tuning tips (which codec is faster, hdparm tricks etc)
- tutorials (how to rip dvd etc)
- how to make gui skins
etc
ie everything which is interesting, but not option descriptions even if
they're long

maybe the the installaton could be separated from html docs and put to
INSTALL text file, maybe install.html and then drop the text version?

> Hmm, some descriptions are really long, but then again MEncoder is
> complex, let's face it..
agree
look at the bash manpage... or even the cvs manpage...
mplayer's manpage isn't so big yet :)

> Maybe we should reorganize the man page (again) and put the more
> advanced options at the end.  Currently we have
> 
> DEMUXER/STREAM OPTIONS
> DECODING/FILTERING OPTIONS
> OSD/SUB OPTIONS
> AUDIO OUTPUT OPTIONS (MPLAYER ONLY)
> VIDEO OUTPUT OPTIONS (MPLAYER ONLY)
> PLAYER OPTIONS (MPLAYER ONLY)
> ENCODING OPTIONS (MENCODER ONLY)
> KEYBOARD CONTROL
> SLAVE MODE PROTOCOL
> 
> I propose this:
> 
> KEYBOARD CONTROL
> PLAYER OPTIONS (MPLAYER ONLY)
> DEMUXER/STREAM OPTIONS
> OSD/SUB OPTIONS
> AUDIO OUTPUT OPTIONS (MPLAYER ONLY)
> VIDEO OUTPUT OPTIONS (MPLAYER ONLY)
> DECODING/FILTERING OPTIONS
> ENCODING OPTIONS (MENCODER ONLY)
> SLAVE MODE PROTOCOL

dunno. why?

> I don't know if we should use new sections or not, but swscaler* and
> vop.txt do not belong in tech/, they should be merged into the man
> page.  Even if we overload the man page I think it's better than to
> duplicate the information.
yes.

if it's getting overload we still can separate libavc-opts to new section of
manpage...

>  > > > > imho manpage should not have big complete examples, it's the job of the
>  > > > > tutorial-like docs. manpage may have simple example, like
>  > > > > -vop filter[=param[:param2]][,filter2...]
>  > > > >    ...
>  > > > >    example: 
>  > > > >    -vop scale=640:-2,rgb2bgr,pp=0x22
>  > > > 
>  > > > I more like centralized examples of _basic_ really often 
>  > > > used things, they belong in a manpage IMHO as it's the first 
>  > > > place someone looks at. Otherwise users have to search them
>  > > > in the whole documentation which they probably won't do.
>  > > > But I agree for specific long guides (dxr3,dvb,tvout,etc).
>  > > 
>  > > imho the real-life examples (how to encode a file etc) should be in the
>  > > tutorial, never in the manpage.
>  > > if an example demonstrates more than 1 options, then it belongs to the
>  > > tutorial rather than an option description.
>  > hmm, I partly agree: Sometimes it's good imho to have a basic 
>  > working example for sthg (tv recording/whatever)
> 
> We should have examples and currently I do not see a good place to put
> them in the HTML docs, so the man page is not that bad, I think.
maybe

>  > If there will be a good encoding guide, some/many/most of the mencoder  
>  > examples should go there. IMHO the actual "guide" is not 
>  > detailed enough, for example: it should include a guide to 
>  > lavcoptions (b frames, bitrate, all others etc).
> 
> Just look at the number of mencoder questions that come up on -users,
> it's much more than mplayer stuff and many aren't even RTFM.  There
> was a tutorial floating around on -users, we should try to merge this
> into encoding.html.

yes. or we need someone who is familiar with ripping tricks etc and also
known mencoder and libavcodec options well

unfortunately those guides floating are written by beginners who are proud
that they could encode and avi and asap write a guide about it :)


A'rpi / Astral & ESP-team

--
Developer of MPlayer, the Movie Player for Linux - http://www.MPlayerHQ.hu