[BusyBox] more usage message fun

[Manuel Novoa III]

Evin,

On Thu, 15 Feb 2001, Evin Robertson wrote:
> 
> The enum and DO_COMMA macro stuff introduced into usage.h seemed a
> little complicated, so I played with it to see if I could make it
> simpler.

It certainly isn't as clean as I would have liked.  My original approach used a
small C program to build the one-big-usage-string from a much-less-modified
usage.c and instead of counting to find the correct usage message, it actually
put the offset from the start of the string into the applet structure.  Erik
didn't like that approach because he didn't want to require two different
compilers in a cross-compiling environment.

> I'm not sure the result is much easier to understand, but it's a
> little bit smaller, both in source size and object size.  I combined
> usage.h and applets.h, creating entries which now look like:
(stuff omitted) 
> The actual build process might not be much easier to understand, but I
> think it's easier to read.

I personally think you're approach is cleaner, but I think the usage messages
were originally put in a separate file in order to factilitate multi-language
support.

> With this patch, applets.h has three #include passes taken at it: one
> for prototypes, one for the BB_applet applets[] array, and one for for
> the usage_messages[] string.
> 
> I also changed some of the repeated spaces into tab characters, and
> removed one duplicated applet's name which was missed in the recent
> usage surgery.
> 
> There are a few gotchas with my code, however.  As is, it doesn't
> support multiple applets having the same help message, but I think
> this only affects people typing "[ --help".  

I noticed you changed zcat --help behaviour as well.

>         Also, I have some rather
> nasty macro stuff going on:
(example preprocessor code omitted)
> This is necessary because C won't allow #ifdefs inside macro
> arguments.  I'm not even 100% sure what I have is legal, though it
> works on both gcc and msvc.

Yes, it is legal and it certainly less nasty (in my opinion) than what I had
done.
 
> This patch reduces the size of each applet by about 4 bytes because it
> shrinks the BB_applet struct, removing the 'int usage_index;'

The only drawback to this that I see is the one you mentioned already... you
can't share usage messages as-is.
  
> show_usage now assumes that the help messages occur in the same order
> as the applets in applets[].  The purpose of the merge of usage.h and
> applets.h was to prevent the possibility that they could get jumbled.
>
> It applies cleanly to CVS as of Feb 15, 9PM EST.

You need to change the trailing ','s to ')'s for dpkg, dumpkmap, and dutmp.

I'm thinking you could use your approach while still keeping all the usage
strings in a seperate file.  You could do something like

(from applets.h)
{change all APPLET(a,b,c,d,e) to APPLET(a,b,c) }
...
#elif defined(MAKE_USAGE)
  #ifdef BB_FEATURE_TRIVIAL_HELP
    #define APPLET(a,b,c) b##_trivial_usage "\0"
    #define APPLET_NOUSAGE(a,b,c) "\0"
  #else
    #define APPLET(a,b,c) b##_trivial_usage "\n\n" b##_full_usage "\0"
    #define APPLET_NOUSAGE(a,b,c) "\0"
  #endif
  const char usage_messages[] =
...
#ifdef BB_AR
	APPLET("ar", ar_main, _BB_DIR_USR_BIN)
#endif
...

(from usage.h)
...
#ifdef BB_AR
#define ar_main_trivial_usage \
	"-[ovR]{ptx} archive filenames"
#define ar_main_full_usage \
	"Extract or list files from an ar archive.\n\n" \
	"Options:\n" \
	"\t-o\t\tpreserve original dates\n" \
	"\t-p\t\textract to stdout\n" \
	"\t-t\t\tlist\n" \
	"\t-x\t\textract\n" \
	"\t-v\t\tverbosely list files processed\n" \
	"\t-R\t\trecursive action"
#endif
...

Manuel