[MPlayer-dev-eng] Is anyone considering docbook for the man page ?

[Dirk]

Alban Bedel wrote:

>Hi Diego Biurrun,
>
>on Tue, 18 Mar 2003 01:34:42 +0100 you wrote:
>
>  
>
>>The man page is in for an overhaul, no question,
>>maybe even the idea of putting mplayer and mencoder together needs to
>>be revisited.  If you have any bright ideas, step forward.  In the
>>meantime I think that redundancy is our worst enemy.
>>    
>>
>
>I agree with you, fight the redundancy !!!!!
>I'd like to say that I would like to have (someday) a kind of integreted
>help as the man page is growing way to big now. By integrated help i mean
>the possiblity of having mplayer document it self. Something like
>'mplayer -describe fs' would ouput what the man page is saying
>about this option.
>
In our project we finally ended with using a simple struct...

typedef struct
{
  int val;  // same val as getopt() returnes after parsing another arg 
successfully
  char *option_s; // the option as string... same string as used in 
struct option
  char *optarg; // optarg
  char *desc;    // the simple usage
 char *more_desc;   // MORE explanation
// (void)
} st_usage_t;

then we made an array of this including EVERY option we have..

st_usage_t usage[] =
{
  {OPT_HELP, "help", NULL, "help output", "i said help output.."},
  ...

}


the only thing left is a function that generates the usage.. or 
something like a man page (with more_desc) ...

render_usage (st_usage_t **usage, int opt)

if opt is set only the usage for that opt will be rendered (useful for 
the case that the option failed and you want to show it's usage again 
after the error msg..) if it's 0 or -1 ... all usages in that array will 
be "rendered"...

all this of course doesnt require getopt() but there is always the 
chance to include getopt() "conformity" w/o the need to change/break any 
existing code or to end with a getopt() that not only parses the cmdline 
but also "decides" what happens after...

the common use of getopt() is having a switch() ...

while (getopt() != -1)
  {
   switch()
   {
bla... your "workflow"...
}
}


that's not the way to go if you want getopt() only to "parse" the 
cmdline for "conformity"...

typedef struct
{
  int val;
   char *optarg;
} st_opts_t


st_opts_t opts[MAX_OPTIONS];
x = 0;
while ((c = getopt()) != -1)
{
  opts[x].val = c;
  if (optarg)
    opts[x++].optarg = optarg;
}

ok.. i won't talk about the use of st_opts_t but this way you can 
include getopt() everywhere in main() w/o any effects... blablabla...

i'm awaiting (creative) flames now..

Dirk