git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Teng Long <dyroneteng@gmail.com>
Cc: avarab@gmail.com, git@vger.kernel.org, sunshine@sunshineco.com,
	tenglong.tl@alibaba-inc.com
Subject: Re: [PATCH v5 3/3] notes.c: introduce "--separator" option
Date: Thu, 16 Feb 2023 15:22:16 -0800	[thread overview]
Message-ID: <xmqq7cwhnql3.fsf@gitster.g> (raw)
In-Reply-To: <a74c96d6dd23f2f1df6d3492093f3fd27451e24c.1676551077.git.dyroneteng@gmail.com> (Teng Long's message of "Thu, 16 Feb 2023 21:05:05 +0800")

Teng Long <dyroneteng@gmail.com> writes:

> When appending to a given notes object and the appended note is not
> empty too, we will insert a blank line at first which separates the
> existing note and the appended one, which as the separator.

", which as the separator" does not sound grammatically correct.
Without that part, the above is a perfectly readable description of
the current behaviour.

> Sometimes, we want to use a specified <separator> as the separator. For
> example, if we specify as:
>
>     * --separator='------': we will insert "------\n" as the separator,
>     because user do not provide the line break char at last, we will add
>     the trailing '\n' compatibly.

In a way compatible to what?  I think s/compatibly// would be even
easier to read.  I think you are doing that for convenience.

>     * --separator='------\n': we will insert as-is because it contains
>     the line break at last.

If this behaviour gets spelled out like this, it needs to be
justified.

After seeing that "------" gives the user these dashes on its own
single line, wouldn't a natural expectation by the user be to see a
line with dashes, followed by a blank line, if you give "------\n"?
How do you justify removal of that newline in a way that is easy to
understand to readers?

I am not saying that you should allow --separator="---\n\n\n" to
give three blank lines between paragraphs. I think it makes sense to
keep the stripspace in the code after a paragraph gets added. I just
prefer to see it done as our design choice, not "because there is
stripspace that removes them", i.e. what the code happens to do. 

>     * not specified --separator option: will use '\n' as the separator
>     when do appending and this is the default behavour.

s/not specified --separator option/no --separator option/; the way
you phrased can be misread for

	git notes --separator -m foo -m bar

i.e. any additional specifics is not given but --separator is still
on the command line.  But I do not think you meant that---rather
this entry is what happens by default, i.e. a blank line separates
each paragraph.

>     * --separator='': we specify an empty separator which has the same
>     behavour with --separator='\n' and or not specified the option.

I do not quite see why it is necessary to spell this out.  Isn't
this a natural consequence of the first one (i.e. "six dashes
without any terminating LF gets a line with dashes plus LF"
naturally extends to "0 dashes without any terminating LF gets a
blank line")?

> In addition, if a user specifies multple "-m" with "--separator", the
> separator should be inserted between the messages too, so we use
> OPT_STRING_LIST instead of OPT_CALLBACK_F to parse "-m" option, make
> sure the option value of "--separator" been parsed already when we need
> it.

This is hard to grok.  Is it an instruction to whoever is
implementing this new feature, or is it an instruct to end-users
telling that they need to give --separator before they start giving
-m <msg>, -F <file>, -c <object>, etc.?

> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index efbc10f0..5abe6092 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -11,7 +11,7 @@ SYNOPSIS
>  'git notes' [list [<object>]]
>  'git notes' add [-f] [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]

Doesn't add allow you to say

	$ git notes add -m foo -m bar

Shouldn't it also honor --separator to specify an alternate
paragraph break?

> -'git notes' append [--allow-empty] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]
> +'git notes' append [--allow-empty] [--separator] [-F <file> | -m <msg> | (-c | -C) <object>] [<object>]

"--separator" -> "--separator=<paragraph-break>" or something?

> @@ -86,7 +86,9 @@ the command can read the input given to the `post-rewrite` hook.)
>  
>  append::
>  	Append to the notes of an existing object (defaults to HEAD).
> -	Creates a new notes object if needed.
> +	Creates a new notes object if needed. If the note and the
> +	message are not empty, "\n" will be inserted between them.
> +	Use the `--separator` option to insert other delimiters.

"\n" is so, ... programmer lingo?  "A blank line" is inserted
between these paragraphs.

> +--separator <separator>::
> +	The '<separator>' inserted between the note and message
> +	by 'append', "\n" by default. A custom separator can be

I see no reason to single out 'append'; "add -m <msg> -m <msg>"
follows exactly the same paragraph concatenation logic in the
current code, no?  If we allow customized paragraph separators,
we should use the same logic there as well.

It probably is simpler to explain if you treat the "current note in
'append'" as if the text were just "earlier paragraphs", to which
more paragraphs taken from each -m <msg> and -F <file> are
concatenated, with paragraph break before each of them.  In the case
of 'add', there happens to be zero "earlier paragraphs", but
everything else gets concatenated the same way, no?

> +	provided, if it doesn't end in a "\n", one will be added
> +	implicitly .

Funny punctuation.

  reply	other threads:[~2023-02-16 23:23 UTC|newest]

Thread overview: 186+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-10-13  5:56 [RFC PATCH 0/2] notes.c: introduce "--no-blankline" option Teng Long
2022-10-13  5:56 ` [RFC PATCH 1/2] " Teng Long
2022-10-13  6:06   ` Junio C Hamano
2022-10-17 13:19     ` Teng Long
2022-10-13  9:31   ` Ævar Arnfjörð Bjarmason
2022-10-17 13:33     ` Teng Long
2022-10-13  5:56 ` [RFC PATCH 2/2] notes.c: fixed tip when target and append note are both empty Teng Long
2022-10-13  9:36   ` Ævar Arnfjörð Bjarmason
2022-10-13 10:10     ` Phillip Wood
2022-10-13 10:23       ` Ævar Arnfjörð Bjarmason
2022-10-15 19:40         ` Phillip Wood
2022-10-18  3:25       ` Teng Long
2022-10-18  8:08       ` Teng Long
2022-10-18  3:11     ` Teng Long
2022-10-18  9:23       ` Ævar Arnfjörð Bjarmason
2022-11-07 13:57 ` [PATCH v2 0/3] notes.c: introduce "--blank-line" option Teng Long
2022-11-07 13:57   ` [PATCH v2 1/3] " Teng Long
2022-11-07 14:45     ` Ævar Arnfjörð Bjarmason
2022-11-07 15:45       ` Eric Sunshine
2022-11-07 17:22         ` Ævar Arnfjörð Bjarmason
2022-11-07 21:46           ` Taylor Blau
2022-11-07 22:36             ` Ævar Arnfjörð Bjarmason
2022-11-08  0:32               ` Taylor Blau
2022-11-08  3:45       ` Teng Long
2022-11-08 13:06       ` Teng Long
2022-11-08 13:22         ` Ævar Arnfjörð Bjarmason
2022-11-09  6:35           ` Teng Long
2022-11-07 15:06     ` Ævar Arnfjörð Bjarmason
2022-11-08  6:32       ` Teng Long
2022-11-07 21:47     ` Taylor Blau
2022-11-08  7:36       ` Teng Long
2022-11-07 13:57   ` [PATCH v2 2/3] notes.c: fixed tip when target and append note are both empty Teng Long
2022-11-07 14:40     ` Ævar Arnfjörð Bjarmason
2022-11-07 21:51       ` Taylor Blau
2022-11-07 22:33         ` Ævar Arnfjörð Bjarmason
2022-11-07 22:45           ` Taylor Blau
2022-11-08  8:55           ` Teng Long
2022-11-07 13:57   ` [PATCH v2 3/3] notes.c: drop unreachable code in "append_edit()" Teng Long
2022-11-07 14:41     ` Ævar Arnfjörð Bjarmason
2022-11-07 14:57   ` [PATCH v2 0/3] notes.c: introduce "--blank-line" option Ævar Arnfjörð Bjarmason
2022-11-09  7:05     ` Teng Long
2022-11-09  7:06     ` Teng Long
2022-11-09  9:06   ` [PATCH v3 0/5] notes.c: introduce "--no-blank-line" option Teng Long
2022-11-09  9:06     ` [PATCH v3 1/5] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2022-11-09  9:06     ` [PATCH v3 2/5] notes.c: cleanup for "designated init" and "char ptr init" Teng Long
2022-11-09  9:06     ` [PATCH v3 3/5] notes.c: drop unreachable code in 'append_edit()' Teng Long
2022-11-09  9:06     ` [PATCH v3 4/5] notes.c: provide tips when target and append note are both empty Teng Long
2022-11-09  9:06     ` [PATCH v3 5/5] notes.c: introduce "--no-blank-line" option Teng Long
2022-11-28 14:20     ` [PATCH v3 0/5] " Teng Long
2022-11-29  1:10       ` Junio C Hamano
2022-11-29 22:53         ` Taylor Blau
2022-11-29 12:57     ` Teng Long
2022-11-29 13:19       ` Junio C Hamano
2022-12-15 12:48         ` Teng Long
2022-12-19  3:03           ` Eric Sunshine
2022-12-21  9:16             ` Teng Long
2022-12-21 11:35               ` Junio C Hamano
2022-12-22  9:30             ` Teng Long
2022-12-23  1:36               ` Eric Sunshine
2023-01-12  2:48     ` [PATCH v4 0/5] notes.c: introduce "--separator" optio Teng Long
2023-01-12  2:48       ` [PATCH v4 1/5] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-01-15  4:53         ` Eric Sunshine
2023-01-28 11:22           ` Teng Long
2023-01-12  2:48       ` [PATCH v4 2/5] notes.c: cleanup for "designated init" and "char ptr init" Teng Long
2023-01-12  9:51         ` Ævar Arnfjörð Bjarmason
2023-01-28 11:33           ` Teng Long
2023-01-12  2:48       ` [PATCH v4 3/5] notes.c: drop unreachable code in 'append_edit()' Teng Long
2023-01-15 20:59         ` Eric Sunshine
2023-01-15 21:10           ` Eric Sunshine
2023-01-28 11:50           ` Teng Long
2023-01-30  5:38             ` Eric Sunshine
2023-02-01  8:08               ` Teng Long
2023-01-12  2:48       ` [PATCH v4 4/5] notes.c: provide tips when target and append note are both empty Teng Long
2023-01-12  9:52         ` Ævar Arnfjörð Bjarmason
2023-01-15 21:28         ` Eric Sunshine
2023-01-12  2:48       ` [PATCH v4 5/5] notes.c: introduce "--separator" option Teng Long
2023-01-12  9:53         ` Ævar Arnfjörð Bjarmason
2023-01-15 22:04           ` Eric Sunshine
2023-01-15 22:15         ` Eric Sunshine
2023-02-16 13:05       ` [PATCH v5 0/3] " Teng Long
2023-02-16 13:05         ` [PATCH v5 1/3] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-02-16 18:39           ` Junio C Hamano
2023-02-20  3:34             ` Teng Long
2023-02-16 13:05         ` [PATCH v5 2/3] notes.c: cleanup for "designated init" Teng Long
2023-02-16 18:39           ` Junio C Hamano
2023-02-16 13:05         ` [PATCH v5 3/3] notes.c: introduce "--separator" option Teng Long
2023-02-16 23:22           ` Junio C Hamano [this message]
2023-02-20 14:00             ` Teng Long
2023-02-21 21:31               ` Junio C Hamano
2023-02-22  8:17                 ` Teng Long
2023-02-22 23:15                   ` Junio C Hamano
2023-02-23  7:29         ` [PATCH v6 0/3] " Teng Long
2023-02-23  7:29           ` [PATCH v6 1/3] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-02-23  7:29           ` [PATCH v6 2/3] notes.c: cleanup for "designated init" Teng Long
2023-02-23  7:29           ` [PATCH v6 3/3] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-02-23 18:21             ` Junio C Hamano
2023-02-28 14:11               ` Teng Long
2023-02-25 21:30             ` Junio C Hamano
2023-02-28 14:14               ` Teng Long
2023-03-27 13:13           ` [PATCH v6 0/3] notes.c: introduce "--separator" option Teng Long
2023-03-28 14:28           ` [PATCH v7 0/4] " Teng Long
2023-03-28 14:28             ` [PATCH v7 1/4] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-03-28 14:28             ` [PATCH v7 2/4] notes.c: cleanup for "designated init" Teng Long
2023-03-29 22:17               ` Junio C Hamano
2023-03-28 14:28             ` [PATCH v7 3/4] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-03-28 15:37               ` Junio C Hamano
2023-03-29 14:15                 ` Teng Long
2023-03-29 21:48                   ` Junio C Hamano
2023-04-13  9:36                     ` Teng Long
2023-03-28 14:28             ` [PATCH v7 4/4] notes.c: don't do stripespace when parse file arg Teng Long
2023-03-28 15:54               ` Junio C Hamano
2023-03-29 12:06                 ` Teng Long
2023-03-29 16:21                   ` Junio C Hamano
2023-04-25 13:34             ` [PATCH 0/6] notes.c: introduce "--separator" option Teng Long
2023-04-25 13:34               ` [PATCH v8 1/6] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-04-25 13:34               ` [PATCH v8 2/6] notes.c: use designated initializers for clarity Teng Long
2023-04-25 13:34               ` [PATCH v8 3/6] t3321: add test cases about the notes stripspace behavior Teng Long
2023-04-25 16:25                 ` Junio C Hamano
2023-04-27  3:47                   ` Teng Long
2023-04-25 13:34               ` [PATCH v8 4/6] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-04-25 17:34                 ` Junio C Hamano
2023-04-27  7:21                   ` Teng Long
2023-04-27 18:21                     ` Junio C Hamano
2023-04-25 17:35                 ` Junio C Hamano
2023-04-25 13:34               ` [PATCH v8 5/6] notes.c: append separator instead of insert by pos Teng Long
2023-04-25 17:47                 ` Junio C Hamano
2023-04-27  7:51                   ` Teng Long
2023-04-25 13:34               ` [PATCH v8 6/6] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-04-25 17:49                 ` Junio C Hamano
2023-04-28  7:40                   ` Teng Long
2023-04-28 18:21                     ` Junio C Hamano
2023-04-28  9:23               ` [PATCH v9 0/6] notes.c: introduce "--separator" option Teng Long
2023-04-28  9:23                 ` [PATCH v9 1/6] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-04-28  9:23                 ` [PATCH v9 2/6] notes.c: use designated initializers for clarity Teng Long
2023-04-28  9:23                 ` [PATCH v9 3/6] t3321: add test cases about the notes stripspace behavior Teng Long
2023-04-28  9:23                 ` [PATCH v9 4/6] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-04-28 20:44                   ` Junio C Hamano
2023-05-06  9:12                     ` Teng Long
2023-05-06  9:22                       ` Teng Long
2023-05-10 19:19                   ` Kristoffer Haugsbakk
2023-05-12  4:07                     ` Teng Long
2023-05-12  7:29                       ` Kristoffer Haugsbakk
2023-05-16 17:00                       ` Junio C Hamano
2023-05-17  3:58                         ` Teng Long
2023-05-17 15:32                           ` Junio C Hamano
2023-06-14  1:02                   ` Junio C Hamano
2023-06-14  1:10                     ` [PATCH] notes: do not access before the beginning of an array Junio C Hamano
2023-06-14  1:41                     ` [PATCH v9 4/6] notes.c: introduce '--separator=<paragraph-break>' option Eric Sunshine
2023-06-14  2:07                       ` Junio C Hamano
2023-06-15  7:13                         ` Jeff King
2023-06-15 19:15                           ` Junio C Hamano
2023-06-19  6:08                             ` Teng Long
2023-06-20 20:36                               ` Junio C Hamano
2023-06-21  2:50                                 ` Teng Long
2023-04-28  9:23                 ` [PATCH v9 5/6] notes.c: append separator instead of insert by pos Teng Long
2023-04-28  9:23                 ` [PATCH v9 6/6] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-04-28 20:46                 ` [PATCH v9 0/6] notes.c: introduce "--separator" option Junio C Hamano
2023-05-01 22:29                 ` Junio C Hamano
2023-05-18 12:02                 ` [PATCH v10 " Teng Long
2023-05-18 12:02                   ` [PATCH v10 1/6] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-05-18 12:02                   ` [PATCH v10 2/6] notes.c: use designated initializers for clarity Teng Long
2023-05-18 12:02                   ` [PATCH v10 3/6] t3321: add test cases about the notes stripspace behavior Teng Long
2023-05-18 12:02                   ` [PATCH v10 4/6] notes.c: introduce '[--[no-]separator|--separator=<paragraph-break>]' option Teng Long
2023-05-18 14:34                     ` Kristoffer Haugsbakk
2023-05-20 10:41                       ` Teng Long
2023-05-20 16:12                         ` Kristoffer Haugsbakk
2023-05-19  0:54                     ` Jeff King
2023-05-27  7:17                       ` Teng Long
2023-05-27 17:19                         ` Jeff King
2023-05-29 11:48                           ` Teng Long
2023-05-18 12:02                   ` [PATCH v10 5/6] notes.c: append separator instead of insert by pos Teng Long
2023-05-18 12:02                   ` [PATCH v10 6/6] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-05-18 13:56                   ` [PATCH v10 0/6] notes.c: introduce "--separator" option Kristoffer Haugsbakk
2023-05-20 10:22                     ` Teng Long
2023-05-18 15:17                   ` Junio C Hamano
2023-05-20 10:59                     ` Teng Long
2023-05-27  7:57                   ` [PATCH v11 0/7] notes.c: introduce "--separator" Teng Long
2023-05-27  7:57                     ` [PATCH v11 1/7] notes.c: cleanup 'strbuf_grow' call in 'append_edit' Teng Long
2023-05-27  7:57                     ` [PATCH v11 2/7] notes.c: use designated initializers for clarity Teng Long
2023-05-27  7:57                     ` [PATCH v11 3/7] t3321: add test cases about the notes stripspace behavior Teng Long
2023-05-27  7:57                     ` [PATCH v11 4/7] notes.c: introduce '--separator=<paragraph-break>' option Teng Long
2023-05-27  7:57                     ` [PATCH v11 5/7] notes.c: append separator instead of insert by pos Teng Long
2023-05-27  7:57                     ` [PATCH v11 6/7] notes.c: introduce "--[no-]stripspace" option Teng Long
2023-05-27  7:57                     ` [PATCH v11 7/7] notes: introduce "--no-separator" option Teng Long
2023-06-01  5:50                     ` [PATCH v11 0/7] notes.c: introduce "--separator" Junio C Hamano
2023-06-03 10:01                       ` Teng Long

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=xmqq7cwhnql3.fsf@gitster.g \
    --to=gitster@pobox.com \
    --cc=avarab@gmail.com \
    --cc=dyroneteng@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=sunshine@sunshineco.com \
    --cc=tenglong.tl@alibaba-inc.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).