You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@kafka.apache.org by Tom Bentley <t....@gmail.com> on 2017/06/16 13:06:02 UTC
Improving tools: --help
Hi,
I noticed that the command line tools could use a little love. For
instance, I was surprised that most of them don't support `--help`, and
generally there are a few inconsistencies.
KIP-14 is dormant and AFAICS no one is working on
https://issues.apache.org/jira/browse/KAFKA-2111 either. So if I'm not
treading on anyone's toes, I would like to improve this situation.
Specifically I propose to:
1. Add support for `--help` for all tools with shell scripts.
2. Include in the help output on non-Windows systems documentation for the
script-implemented `--daemon`, `--name` and `--loggc` options, because
currently they're not very discoverable.
3. Add more standard equivalents for non-UNIXish options (e.g. add
`--consumer-config` as well as `--consumer.config`).
I also noticed that overall Kafka has two option parsing dependencies:
`argparse4j` and `jopt-simple`. Is there a good reason for this? If not
then I could standardize on one at the same time.
Would this require a KIP? If so should I open a new one, or resurrect
KIP-14?
Regards,
Tom
Re: Improving tools: --help
Posted by Tom Bentley <t....@gmail.com>.
> I just checked kafka-topics.sh and the only required argument there is
> --zookeeper option. Not sure if you were thinking of some other command.
>
> I meant that for kafka-topics.sh --create requires --topic (amongst
others), but --list does not.
(For example, using these methods we can say something like:
> - A.requiredIf("B") the given option 'A' requires option 'B'
> - A.requiredUnless("B") the given option 'A' needs to be present if option
> 'B' is not present)
>
> I wasn't able to get that to work for that command. I am sure I am missing
> something but will keep working on it.
>
That's a good start if you can get it working. If the fact that A is
required when B is present is only part of the documentation for A, it
doesn't help me when I scan the documentation of B. But maybe JOptSimple
would document this on B?
imho the best way to deal with this sort of situation is with multiple
usages, see for example `git branch --help` -- it's clear an concise which
options are supported/required with which 'actions'.
Cheers,
Tom
Re: Improving tools: --help
Posted by Mariam John <ma...@us.ibm.com>.
Hi Tom,
I just checked kafka-topics.sh and the only required argument there is
--zookeeper option. Not sure if you were thinking of some other command.
But I understand what you mean. One of the places where I had some trouble
with something related is the kafka-console-consumer command where the
required options are based on whether we are using the new consumer or old
consumer. In JOptSimple there is a way to define "Required Dependent
Options" using the requiredIf or requiredUnless methods
(For example, using these methods we can say something like:
- A.requiredIf("B") the given option 'A' requires option 'B'
- A.requiredUnless("B") the given option 'A' needs to be present if option
'B' is not present)
I wasn't able to get that to work for that command. I am sure I am missing
something but will keep working on it.
Hope this helps.
Regards,
Mariam.
From: Tom Bentley <t....@gmail.com>
To: dev@kafka.apache.org
Date: 06/16/2017 10:32 AM
Subject: Re: Improving tools: --help
That's a great start Mariam, thanks.
Out of interest, how do you handle required arguments for something like
kafka-topics.sh where what's required depends on the 'action' option?
Cheers,
Tom
On 16 June 2017 at 15:55, Mariam John <ma...@us.ibm.com> wrote:
> Hi Tom,
>
> I just wanted to let you know that I am currently working on KAFKA-2111:
> https://issues.apache.org/jira/browse/KAFKA-2111 and am almost done with
> it. The changes that are included in this patch are:
>
> - add --help option to all the commands where it is missing
> - correctly mark all the required options. I noticed that currently we
> rely on the user to add the REQUIRED wording in the option description. I
> have changed this to use the JOptSimple method required() to mark options
> as required. The other good thing about doing it that way is that when
the
> parse method is called, it will automatically check if user has specified
> the required arguments (Right now we rely on
CommandLineUtils.checkRequiredArg
> to do that)
> - Made some minor grammar changes to the option descriptions on some of
> the commands (like ending the description with ., Starting a description
> with caps, some wording changes)
> - Some commands did not have description of what it does - added those
>
>
> I am also looking at https://issues.apache.org/jira/browse/KAFKA-4220
> since it is related to this. So I am currently trying to include this
> changes in the current patchset for KAFKA-2111. It will include:
> - changes to properly catch OptionExceptions when converting the argument
> to different types and print out the error message and command usage
> information rather than throwing a stacktrace exception.
>
> There are close to 20 commands I have made changes to. I will try to push
> something out by end of day today. So I think I will cover 1) from your
> list below and not 2) and 3).
>
> Thanks Tom.
>
> Regards,
> Mariam.
>
>
>
> [image: Inactive hide details for Tom Bentley ---06/16/2017 08:06:11
> AM---Hi, I noticed that the command line tools could use a little]Tom
> Bentley ---06/16/2017 08:06:11 AM---Hi, I noticed that the command line
> tools could use a little love. For
>
> From: Tom Bentley <t....@gmail.com>
> To: dev@kafka.apache.org
> Date: 06/16/2017 08:06 AM
> Subject: Improving tools: --help
> ------------------------------
>
>
>
> Hi,
>
> I noticed that the command line tools could use a little love. For
> instance, I was surprised that most of them don't support `--help`, and
> generally there are a few inconsistencies.
>
> KIP-14 is dormant and AFAICS no one is working on
> https://issues.apache.org/jira/browse/KAFKA-2111 either. So if I'm not
> treading on anyone's toes, I would like to improve this situation.
> Specifically I propose to:
>
> 1. Add support for `--help` for all tools with shell scripts.
> 2. Include in the help output on non-Windows systems documentation for
the
> script-implemented `--daemon`, `--name` and `--loggc` options, because
> currently they're not very discoverable.
> 3. Add more standard equivalents for non-UNIXish options (e.g. add
> `--consumer-config` as well as `--consumer.config`).
>
> I also noticed that overall Kafka has two option parsing dependencies:
> `argparse4j` and `jopt-simple`. Is there a good reason for this? If not
> then I could standardize on one at the same time.
>
> Would this require a KIP? If so should I open a new one, or resurrect
> KIP-14?
>
> Regards,
>
> Tom
>
>
>
Re: Improving tools: --help
Posted by Tom Bentley <t....@gmail.com>.
That's a great start Mariam, thanks.
Out of interest, how do you handle required arguments for something like
kafka-topics.sh where what's required depends on the 'action' option?
Cheers,
Tom
On 16 June 2017 at 15:55, Mariam John <ma...@us.ibm.com> wrote:
> Hi Tom,
>
> I just wanted to let you know that I am currently working on KAFKA-2111:
> https://issues.apache.org/jira/browse/KAFKA-2111 and am almost done with
> it. The changes that are included in this patch are:
>
> - add --help option to all the commands where it is missing
> - correctly mark all the required options. I noticed that currently we
> rely on the user to add the REQUIRED wording in the option description. I
> have changed this to use the JOptSimple method required() to mark options
> as required. The other good thing about doing it that way is that when the
> parse method is called, it will automatically check if user has specified
> the required arguments (Right now we rely on CommandLineUtils.checkRequiredArg
> to do that)
> - Made some minor grammar changes to the option descriptions on some of
> the commands (like ending the description with ., Starting a description
> with caps, some wording changes)
> - Some commands did not have description of what it does - added those
>
>
> I am also looking at https://issues.apache.org/jira/browse/KAFKA-4220
> since it is related to this. So I am currently trying to include this
> changes in the current patchset for KAFKA-2111. It will include:
> - changes to properly catch OptionExceptions when converting the argument
> to different types and print out the error message and command usage
> information rather than throwing a stacktrace exception.
>
> There are close to 20 commands I have made changes to. I will try to push
> something out by end of day today. So I think I will cover 1) from your
> list below and not 2) and 3).
>
> Thanks Tom.
>
> Regards,
> Mariam.
>
>
>
> [image: Inactive hide details for Tom Bentley ---06/16/2017 08:06:11
> AM---Hi, I noticed that the command line tools could use a little]Tom
> Bentley ---06/16/2017 08:06:11 AM---Hi, I noticed that the command line
> tools could use a little love. For
>
> From: Tom Bentley <t....@gmail.com>
> To: dev@kafka.apache.org
> Date: 06/16/2017 08:06 AM
> Subject: Improving tools: --help
> ------------------------------
>
>
>
> Hi,
>
> I noticed that the command line tools could use a little love. For
> instance, I was surprised that most of them don't support `--help`, and
> generally there are a few inconsistencies.
>
> KIP-14 is dormant and AFAICS no one is working on
> https://issues.apache.org/jira/browse/KAFKA-2111 either. So if I'm not
> treading on anyone's toes, I would like to improve this situation.
> Specifically I propose to:
>
> 1. Add support for `--help` for all tools with shell scripts.
> 2. Include in the help output on non-Windows systems documentation for the
> script-implemented `--daemon`, `--name` and `--loggc` options, because
> currently they're not very discoverable.
> 3. Add more standard equivalents for non-UNIXish options (e.g. add
> `--consumer-config` as well as `--consumer.config`).
>
> I also noticed that overall Kafka has two option parsing dependencies:
> `argparse4j` and `jopt-simple`. Is there a good reason for this? If not
> then I could standardize on one at the same time.
>
> Would this require a KIP? If so should I open a new one, or resurrect
> KIP-14?
>
> Regards,
>
> Tom
>
>
>
Re: Improving tools: --help
Posted by Mariam John <ma...@us.ibm.com>.
Hi Tom,
I just wanted to let you know that I am currently working on KAFKA-2111:
https://issues.apache.org/jira/browse/KAFKA-2111 and am almost done with
it. The changes that are included in this patch are:
- add --help option to all the commands where it is missing
- correctly mark all the required options. I noticed that currently we rely
on the user to add the REQUIRED wording in the option description. I have
changed this to use the JOptSimple method required() to mark options as
required. The other good thing about doing it that way is that when the
parse method is called, it will automatically check if user has specified
the required arguments (Right now we rely on
CommandLineUtils.checkRequiredArg to do that)
- Made some minor grammar changes to the option descriptions on some of the
commands (like ending the description with ., Starting a description with
caps, some wording changes)
- Some commands did not have description of what it does - added those
I am also looking at https://issues.apache.org/jira/browse/KAFKA-4220 since
it is related to this. So I am currently trying to include this changes in
the current patchset for KAFKA-2111. It will include:
- changes to properly catch OptionExceptions when converting the argument
to different types and print out the error message and command usage
information rather than throwing a stacktrace exception.
There are close to 20 commands I have made changes to. I will try to push
something out by end of day today. So I think I will cover 1) from your
list below and not 2) and 3).
Thanks Tom.
Regards,
Mariam.
From: Tom Bentley <t....@gmail.com>
To: dev@kafka.apache.org
Date: 06/16/2017 08:06 AM
Subject: Improving tools: --help
Hi,
I noticed that the command line tools could use a little love. For
instance, I was surprised that most of them don't support `--help`, and
generally there are a few inconsistencies.
KIP-14 is dormant and AFAICS no one is working on
https://issues.apache.org/jira/browse/KAFKA-2111 either. So if I'm not
treading on anyone's toes, I would like to improve this situation.
Specifically I propose to:
1. Add support for `--help` for all tools with shell scripts.
2. Include in the help output on non-Windows systems documentation for the
script-implemented `--daemon`, `--name` and `--loggc` options, because
currently they're not very discoverable.
3. Add more standard equivalents for non-UNIXish options (e.g. add
`--consumer-config` as well as `--consumer.config`).
I also noticed that overall Kafka has two option parsing dependencies:
`argparse4j` and `jopt-simple`. Is there a good reason for this? If not
then I could standardize on one at the same time.
Would this require a KIP? If so should I open a new one, or resurrect
KIP-14?
Regards,
Tom