cURL / Mailing Lists / curl-users / Single Mail

curl-users

Re: Revamping the --help list?

From: Tatsuhiro Tsujikawa <tatsuhiro.t_at_gmail.com>
Date: Mon, 8 Jun 2015 21:13:20 +0900

Hi,

On Mon, Jun 8, 2015 at 2:40 AM, Rodrigo Zanatta Silva <
rodrigozanattasilva_at_gmail.com> wrote:

> I think it is a great idea! Some time ago, I say about this idea!
>
> I just think you can have two (or more) layers of help. When someone say
> curl --help, just show the common thing. Newbie that start using curl just
> want to download a URL. Let's assume he will use the most common options
> with the most common protocol (HTTP).
>
> Like my last idea, you can introduce this command:
> curl --help
> curl --help-complete
>
> And there is another idea. Show the help for the protocol
> curl --help-HTTP
> curl --help-FTP
> ...
>
> But I think it will create more verbose than help.
>
> I know that for you, it is difficult to say what is common option. But the
> community can help to say what need to be in the small help and what don't
> need. This is arbitrary, but the newbie don't care about it. He just want
> to make it work!
>
>
​In aria2 project [1]​, we also faced the similar problem. Let me
introduce how we improved our help system. It includes similar things you
discussed already.

Basically, we added 2 features:

1. tagging; same tag can be added to the multiple options, and an option
can have multiple different tags. We can filter options to output by this
tag.
2. substring match; by supplying substring to --help option, we only show
options which contain this keyword in its long option form

We have now following tags:
#basic, #advanced, #http, #https, #ftp, #metalink, #bittorrent, #cookie,
#hook, #file, #rpc, #checksum, #experimental, #deprecated, #help, #all

For example, #http tag is usually added to the options related to HTTP
protocol. If we invoke 'aria2c -h#http', only options with #http tag will
be shown. The interesting tag is #basic and #advanced. When we invoke
'aria2c -h', then only options with #basic tag are shown. OTOH, options
with #advanced means this is advanced feature, and normally should not be
cared.

The substring matching is very useful, when you forgot (sorry) exact option
name, but can come up with substring inside it. For example, when we'd
like to enable HTTP pipelining, but forgot to the full option name,
invoking 'aria2c -hpipelining' shows only options containing "pipelining"
in its name. In this case, it outputs --enable-http-pipelining option only.

Thanks to the maintainer, aria2 is heavily packaged in most Linux
distributions, and this help system is there quite some time now, so you
can play around it by yourself.

[1] http://aria2.sourceforge.net/

Best regards,
Tatsuhiro Tsujikawa

>
> 2015-06-07 13:21 GMT-03:00 Daniel Stenberg <daniel_at_haxx.se>:
>
>> Hi friends!
>>
>> There's little doubt that the huge and alpha sorted --help output can be
>> a bit intimidating to users and it can easily make the options you really
>> need drown among all the others. We are at over 170 options now and the
>> list keeps growing.
>>
>> What to do about it that will be helpful?
>>
>> spaceone filed this pull-request https://github.com/bagder/curl/pull/252
>> that reorders the list and adds subtitles. The latest incarnation of that
>> suggestion can be seen here: https://bpaste.net/show/2ea7b5081e50
>>
>> I'm however not completely sold on that method as the final solution to
>> the problem, so I'm suggesting another take at the problem as detailed in
>> my comment to the PR here:
>> https://github.com/bagder/curl/pull/252#issuecomment-109327337
>>
>> What do YOU think?
>>
>> --
>>
>> / daniel.haxx.se
>> -------------------------------------------------------------------
>> List admin: http://cool.haxx.se/list/listinfo/curl-users
>> FAQ: http://curl.haxx.se/docs/faq.html
>> Etiquette: http://curl.haxx.se/mail/etiquette.html
>>
>
>
> -------------------------------------------------------------------
> List admin: http://cool.haxx.se/list/listinfo/curl-users
> FAQ: http://curl.haxx.se/docs/faq.html
> Etiquette: http://curl.haxx.se/mail/etiquette.html
>
>

-------------------------------------------------------------------
List admin: http://cool.haxx.se/list/listinfo/curl-users
FAQ: http://curl.haxx.se/docs/faq.html
Etiquette: http://curl.haxx.se/mail/etiquette.html
Received on 2015-06-08