[MPlayer-dev-eng] [PATCH] Default CDROM device on OpenBSD

[Rowan James]

On 03/08/2010, at 8:27 PM, Nicolas George wrote:

> Le sextidi 16 thermidor, an CCXVIII, Rowan James a écrit :
>> I'm just going to throw this out there... why include sections the user
>> can't use in their installed man page at all?
>> 
>> Would it perhaps be better to just replace it with a stub indicating that
>> they're missing a major feature, and a summary of the feature in question?
> 
> MPlayer's man page is huge, one rarely read it from start to end. It is much
> more common to use text search on a keyword to find the needed feature.
> 
> If I find the feature I need is provided by libfoo, but that support for
> libfoo was disabled at build time, well, sudu apt-get install libfoo-dev,
> ./configure --enable-libfoo, and I have what I need.
> 
> If the documentation for libfoo had been replaced by a stub, maybe I would
> not have found the keyword.

TV tuners, various streaming protocols, etc. occupy a lot of space in the man page that I'm unlikely to use, but find myself skipping through over and over again.  Of course, this could probably be better addressed by the splitting suggestion below, et. al.

I did the 'find a feature and install the libraries' pattern a lot when I started using mplayer; so you'd certainly want a pretty verbose stub; *or* - not reduce/stub the mplayer-all version of the page, as you suggest; but reduce the section-specific ones to what the user has configured.

> While I am at it, another wild idea about man page: the man page for zsh is
> huge, thrice as huge as the one for mplayer. But it is split into small,
> manageable parts: man zshbuiltins for builtin functions, man zshzle for the
> line editing system, etc., plus man zshall for all the man pages
> concatenated, allowing a full-text search. It uses the ".so" feature of
> *roff: zshall.1 is very small, and ends with a sequence of ".so
> man1/zshoptions.1", ".so man1/zshbuiltins.1".
> 
> I would find a similar split very useful for mplayer: someone who just wants
> a reminder of the arguments of -ao alsa could type "man mplayer-ao-alsa"
> instead of searching for "alsa" in the whole manpage (the relevant
> occurrence is the seventeenth). Someone looking for something in the video
> filters would type "man mplayer-vf", there would be no risk that his
> full-text search brings him in the description of a VO.

I really like this;  I use the man page a lot, but mostly to look up specific details I know the section for anyway, like x264encopts, lavcopts, etc.

If anyone picks this up, it may even may be better to only go as deep as mplayer-ao, so users could still see the various available (or installed ;)  modules for the same function in the same context, in case the one they're trying to beat into place isn't the best suited.


Regards,
    - Rowan