Re: [PATCH] Documentation: replace - use consistent 'replace reference'

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 27, 2022, 21:01 UTC
Message-ID: <xmqq8rrqkzqe.fsf@gitster.g>
In-Reply-To: <20220427195450.366703-1-debian@onerussian.com>

Yaroslav Halchenko <debian@onerussian.com> writes:

Show 21 quoted lines

> As a new user to 'git replace' I found it a little uncertain about what
> "'replace' reference" documentation was talking since there was only
> "replacement" mentioned in the command summary.  Decided to make it more
> consistent as 'replace reference' after checking that in a few spots there is a
> use of multi word entries within <>.
>
> Signed-off-by: Yaroslav Halchenko <debian@onerussian.com>
> ---
>  Documentation/git-replace.txt | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
> index f271d758c3..71f98edfe3 100644
> --- a/Documentation/git-replace.txt
> +++ b/Documentation/git-replace.txt
> @@ -8,7 +8,7 @@ git-replace - Create, list, delete refs to replace objects
>  SYNOPSIS
>  --------
>  [verse]
> -'git replace' [-f] <object> <replacement>
> +'git replace' [-f] <object> <replace reference>

If we must use a multi-word, perhaps come up with a dashed form to make it still a single token, i.e.

	'git replace' [-f] <object> <replace-reference>

otherwise it forces people to first think "ah, command reads from a file (whose name can be 'replace'), and then..." and then backtrack because the "reference>" part would not be syntactically correct.

You earlier mentioned that you copied the pattern from elsewhere. These places may have to be updated, too.

Show 9 quoted lines

>  'git replace' [-f] --edit <object>
>  'git replace' [-f] --graft <commit> [<parent>...]
>  'git replace' [-f] --convert-graft-file
> @@ -17,16 +17,16 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Adds a 'replace' reference in `refs/replace/` namespace.
> +Adds a 'replace reference' in `refs/replace/` namespace.

And this part becomes 'replace-reference', too.

If we must invent and use such a new multi-word jargon, it probably is a good idea to define it in Documentation/glossary-content.txt

Other than that, looking good.

Thanks.