Re: [PATCH v11 5/9] imap-send: enable specifying the folder using the command line

[Junio C Hamano <gitster@pobox.com>]

Aditya Garg <gargaditya08@live.com> writes:

> Some users may very often want to imap-send messages to a folder
> other than the default set in the config. Add a command line
> argument for the same.
>
> Signed-off-by: Aditya Garg <gargaditya08@live.com>
> ---
>  Documentation/config/imap.adoc   |  5 +++--
>  Documentation/git-imap-send.adoc | 15 +++++++++++----
>  imap-send.c                      |  9 ++++++++-
>  3 files changed, 22 insertions(+), 7 deletions(-)
>
> diff --git a/Documentation/config/imap.adoc b/Documentation/config/imap.adoc
> index 24e88228d0..829d9e0bac 100644
> --- a/Documentation/config/imap.adoc
> +++ b/Documentation/config/imap.adoc
> @@ -1,7 +1,8 @@
>  imap.folder::
>  	The folder to drop the mails into, which is typically the Drafts
> -	folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
> -	"[Gmail]/Drafts". Required.
> +	folder. For example: 'INBOX.Drafts', 'INBOX/Drafts' or
> +	'[Gmail]/Drafts'. Required if `--folder` argument is not used. If
> +	set and `--folder` is also used, `--folder` will be preferred.

Shouldn't these literals be `typeset like this` with backquotes?

More importantly, when we mention that the command line option
trumps the corresponding configuration variable, the more common
verb we use than "prefer" is "override".  Because it is a general
rule that the configuration variable is used as a back-up in case
there is no command line option is given, it is less confusing if
you omitted the last sentence.  Perhaps rewrite the last two
sentence with something like this?

	The IMAP folder to interact with MUST be specified; the
	value of this configuration variable is used as the fallback
	default value when the `--folder` option is not given.

I dunno.

> @@ -37,6 +39,11 @@ OPTIONS
>  --quiet::
>  	Be quiet.
>  
> +-f <folder>::
> +--folder=<folder>::
> +	Specify the folder in which the emails have to saved.
> +	For example: `--folder=[Gmail]/Drafts` or `-f INBOX/Drafts`.
> +
>  --curl::
>  	Use libcurl to communicate with the IMAP server, unless tunneling
>  	into it.  Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND

There are four existing options and this adds another.  I am
debating myself if this deserves a preliminary clean-up patch so
that the enumerated options are more like

	`-v`::
	`--verbose`::
		Be verbose.

If we did so, this patch can add

	`-f` _<folder>_::
	`--folder=<folder>`::
		Specify the folder to save the e-mails in.
		Required.  Defaults to the value of the `imap.folder`
		configuration variable

without worrying about it not following the prevailing (and stale)
style.

If we are not doing a preliminary clean-up patch, what you sent is
more in line.  We'll leave the clean-up to somebody else and adding
one new option in a stale style to 4 existing ones may not be too
bad.  At least such an intermediate state is locally consistent.

Thanks.