Fix the addgroup help output

[Laszlo Papp]

Isaac,

I honestly took my time to address your concerns, but I have never
received any feedback. Please ... ?

Cheers, L.

On Thu, Aug 21, 2014 at 2:43 PM, Laszlo Papp <lpapp at kde.org> wrote:
> On Thu, Aug 21, 2014 at 2:39 PM, Laszlo Papp <lpapp at kde.org> wrote:
>> On Mon, Aug 18, 2014 at 4:39 PM, Isaac Dunham <ibid.ag at gmail.com> wrote:
>>> On Mon, Aug 18, 2014 at 01:51:00PM +0100, Laszlo Papp wrote:
>>>> You completely miss the point. The whole point of the thread is not about
>>>> writing down one personal preference and done. The applets will be still
>>>> inconsistent, and the process will require manual reviews, style
>>>> investigation, and what not. Any reasonable programmer knows that this can
>>>> be automated without serious defect. Others project have done it; I am sure
>>>> busybox would be able to do it if wanted, but I realize this list has heavy
>>>> objection for almost any valid improvement which kind of makes me burning
>>>> out providing suggestions and comments, but that is not a discussion for
>>>> today...
>>>
>>> So far I've seen "This needs to be done *differently*" without much of an
>>> explanation of what "differently" looks like, and "doing it differently
>>> won't work" with little understanding of what the alternatives are.
>>> (And no one trying to look at all the alternatives with pros and cons.)
>>>
>>> The alternatives I can think of:
>>> * have a usage() function for each command.
>>>  This is the way most/many command-line programs are written.
>>>  It sucks worse than what we do.
>>>
>>> * the old way. Also does not work.
>>>
>>> * keep doing it the current way.
>>>  I'm annoyed by writing the //usage: "....\n" part; Laszlo is complaining
>>>  that this approach leaves it manually maintained.
>>>
>>> * move //usage: to just above where each option is implemented.
>>>  Easier to check consistency with code; harder to see functionality.
>>>
>>> * toybox style.
>>> This puts it in the comment at the top:
>>> /* command - explanation
>>>  * copyright 2014 Foo Bar
>>>  * blah blah blah
>>> USE_COMMAND(...) //wraps macro to add new target/help text/option parsing/...
>>> config COMMAND
>>>   bool "command"
>>>   default y
>>>   help
>>>     usage: command [-ab] [-f FOO]
>>>
>>>     Does something to file FOO
>>>     -a Do something
>>>     -b Do something else
>>>     -f Read input from FOO
>>> */
>>>
>>>  This can be ignored and get out of sync with the code, can be brittle,
>>>  but provides one informative help text for both kconfig and the toy/applet.
>>>  It also doesn't require writing //usage:  "\n" for every line, and then
>>>  doing //kconfig:
>>>
>>> * have our getopt alternative use an array like getopt_long() does.
>>>  This mandates changing everything, using getopt32_new for anything we want
>>>  to document, cannot be compressed, means a bit of bloat, and may have other
>>>  limitations.
>>>
>>>
>>> Is there another way that I'm not thinking of, or would anyone like to
>>> expand on the limitations of one of these?
>>> When you refer to another way, please give a sample of what it would
>>> look like, and try to describe what the limits are.
>>
>> 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.