[MPlayer-dev-eng] Re: [PATCH] Audio filter docs for sound.html

[Jonas Jermann]

Hi

On Fri, Jan 04, 2002 at 12:22:10PM +0100, Forjan Fr?d?ric wrote:
> D Richard Felker III wrote:
> >On Thu, Jan 02, 2003 at 12:49:49PM +0100, Forjan Frédéric wrote:
> >
> >>Hi, we can use some cheat for man, this is the idea from another program 
> >>(don't remember the name)...
> >>If you type "man mplayer" general information are showing. If you want 
> >>more information about an option like channels, type "man 
> >>mplayer_channels". I think it is more easy to find doc like this..
> >>I never make a man page so i don't know thd difficulty to do this.
> >
> >
> >Hmm, how is this easier than "man mplayer" followed by "/channels"?
> >
> >Rich
> Because beginners don't know "/" for searching...
A short note at the beginning could help ;)

> And i think the man is too long...
> Do you prefer an big encyclopedia in one volume or ten volume ?

I consider the man page as a database, _not_ as a guide. It 
should at least mention all avaliable options and their syntax. 
It should be used if someone doesn't know how to use option 
"xy". IMHO it's still readable, useable and well structured (at 
least in big window).
The problem is that many option description won't help without
a longer guide (with examples) on how to use them. We have the 
html documentation for that purpose.

I don't like separate volumes. We already have too much! But if 
you want to separate it lavc.1 would be the first step ;)

Another problem (for me at least) is the roff format but 
unfortunately we're forced to use it as it is the most common 
format for manuals. I agree that it would be better to use some 
meta language for the man page (maybe xml) but someone has to do 
it and afair it's not that easy to convert to roff. Btw: man -> 
html should already work quite well (using groff), so it may
somehow be integrated in the html docs.

Regards
    Jonas