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

[Diego Biurrun]

Jonas Jermann writes:
 > On Tue, Aug 27, 2002 at 09:57:44PM +0200, Arpi wrote:
 > > > > > filters), till end of 3 (controls) and more.  It's also easier 
 > > > > > to maintain the docs this way. IMHO, the html docs should more 
 > > > > > be like an accumulation of guides, donno...  Diego?
 > > > > 
 > > > > agree.
 > > > > maybe we should review tech/ section, move options (like lavc-*, swscaler-*
 > > > > etc) to manpage, and keep only developer files (interfaes, how does the
 > > > > demuxer work, file format details etc) in tech/
 > > > 
 > > > hmm, I actually ment to _base_ the manpage on the tech/* docs.
 > > > Shouldn't it be that the manpage is a subset of the particular 
 > > > tech docs? On the other side it is even better if the developers 
 > > > themself write the actual manpage section (as long as it's 
 > > > "user-readable" ;)
 > > 
 > > i'm against redundant docs. it just results desync.
 > > the option description parts of tech/* (mainly written by Michael) imho
 > > belongs to teh manpage, even if they are more technical than r=1 users.
 > > but don't forget that mplayer and especially mencoder is for advanced users
 > > (others should use xine or virtualdub with their mouse). and the advanced
 > > users usually want to know the meaning of teh options, in more detail than 2
 > > words per option (which is actually useless).

Agreed, we should not duplicate descriptions, even if we have very
long descriptions in the man page.  I just removed the filters section
from the HTML.

My opinion:

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

 > > > > maybe make a new section in manpage, so you don't haveto mix the detailed
 > > > > explanation of -lavcopts etc to the common options.
 > > > > 
 > > > > like:
 > > > > 
 > > > > LIBAVCODEC options:
 > > > > ... (files from tech/libavc*.txt)
 > > > > 
 > > > > SWSCALER options: 
 > > > > ...
 > > > 
 > > > hmm, I don't like it but maybe/probably you're right. I just hate 
 > > > separated docs and like the way it is now. Also I don't think 
 > > > it's necessary to include all aspects of the options in the 
 > > > manpage (for example chroma skipping in -vop scale), maybe in a 
 > > why? the purpose of the manpage is to describe all options.
 > Ouff, some options need really _long_ descriptions. I always 
 > thought my patch made them too long ;)

Hmm, some descriptions are really long, but then again MEncoder is
complex, let's face it..

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

 > scale is the only one which doesn't explain _everything_ at the 
 > moment -> see last question, [:c[:p]], and some others...
 
Hey, that's a bug, fix it!
No, seriously, could you add the missing explanation to the man page
please?

 > > > guide section where they are needed. I have a new idea:
 > > i hate the 'docs is separated to 4 parts, guess where is what you're seeking
 > > for' approach. they will read only one, maybe 2 of them (usually html and
 > > faq, sometimes manpage only, sometimes mplayer -h only) but none all.
 > ok, 100% agree on this issue.

Currently it's not very clear where to start and stop reading.  Maybe
we should split the README into README and install and put all the
options in the man page.  This way you will have to touch the HTML
only when you start having problems or want to use some more codecs,
improve performance etc

 > > > Keep it the way it is now and (in future) move all recommend messages
 > > > (use this for this, this is a good choice, this is fast, what to do 
 > > > in which cases, bitrate?,..) to a encoding guide. Maybe with separated
 > > > sections (dvd, vcd (mencvcd), tv, ..., donno).
 > > it's the tutorial.
 > > but i'm talking about the description of -lavcopts etc which imho belongs to
 > > teh manpage rather than tech/*
 > I know, agree. But no new sections IMHO.

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.

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

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


Diego