Fix the addgroup help output

[Isaac Dunham]

On Fri, Oct 31, 2014 at 06:42:23PM +0000, Laszlo Papp wrote:
> Isaac,
> 
> I honestly took my time to address your concerns, but I have never
> received any feedback. Please ... ?
> 
> Cheers, L.

Sorry about that.

My intent was not to argue for one approach or another; I'd been hoping
to get the discussion to proceed by making people think about how the
meta-information should be stored.

Now, commenting on your proposal:
> >> Yes, there is another (and better) way IMHO. Let us put the help text
> >> of the applet here that the original patch in this thread was
> >> touching:
> >>
> >> //usage:#define addgroup_trivial_usage
> >> //usage:       "[-g GID] [-S] " IF_FEATURE_ADDUSER_TO_GROUP("[USER] ") "GROUP"
> >> //usage:#define addgroup_full_usage "\n\n"
> >> //usage:       "Add a group" IF_FEATURE_ADDUSER_TO_GROUP(" or add a
> >> user to a group") "\n"
> >> //usage:     "\n    -g GID  Group id"
> >> //usage:     "\n    -S  Create a system group"
> >>
> >> Proposal:
> >>
> >> /* @usage: desc
> >>  * -g/--gid argdesc
> >>  * -S
> >>  */
> >>
> >> It is just for the very basic, but I am sure the syntax could be
> >> extended to allow custom cookies and brownies, too. Then, the
> >> buildsystem would generate the code for the actual help text in the
> >> background.
> >
> > This is obviously C comment hack, but this could also be made into a
> > nicer descriptive language, like json, etc. That is not a big problem
> > AFAICT, but the idea remains, only type the metadata, not the all the
> > noise.
For me, the annoying part is converting the usage from plain text to
formatting and keywords. Yes, I know how to write 
//usage:"\n   -f\tfrobnicate the output"

but it's a whole lot nicer when I can simply type
   -f	frobnicate the output
(with no extra prefixes or formatting).
The example you gave *looks* like it's going in the right direction.

It would be hard to get much simpler than that; I suppose that if you
have some magic so you can go
-f/--frobnicate frobnicate the output
and get
   -f,--frobnicate	frobnicate the output

(ie, build system handles indentation) it might be preferable.
But the gains there are debateable.

I know C, shell, and a little sed and awk, and can write troff or markdown.
I don't know XML, json, and so on, and I don't want to write the help for
new applets in yet another language that I don't know.  The closer we get
to raw output, the better.

But there is the detail of handling the plethora of config options.

Using your proposal as a starting point, I might suggest something like this
(for a hypothetical applet "foo", optionally having the "--frobnicate"
option):
/* CONFIG_FOO usage: does foo to input
 * -b	do bar
 * -o FILE	write to FILE
 */

/* CONFIG_FOO_FROBNICATE usage:
 * -f,--frobnicate	frobnicate the output
 */

But I'm not quite sure how to handle wanting a summary like this:
Usage: foo [-bf] [-o FILE] [FILE...]

I suppose we could add a second line specifying operands:

/* CONFIG_FOO usage: does foo to input files
 * [FILE...]
 * -b   do bar
 * -o FILE      write to FILE
 */

where the second line is appended to the short usage.

Thanks,
Isaac Dunham