Re: [PATCH] branch: adjust documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 29, 2024, 19:33 UTC
Message-ID: <xmqqcysff4l7.fsf@gitster.g>
In-Reply-To: <cbaf17e7-37a6-4c2e-82ba-65fe41dd86b1@gmail.com>

Rubén Justo <rjusto@gmail.com> writes:

Show 14 quoted lines

> If we wisely choose the placeholder, perhaps we can write:
>
>     -m [<one>] <two>::
> 	Renames <one> (the current branch is used when not given) to
> 	a new name <two>, together with its reflog and configuration
> 	settings ...
>
> And if <one> is _good enough_ then "current branch is used when ..."
> should seem somewhat redundant.  So it could be possible to end up
> having something like:
>
>     -m [<one>] <two>::
> 	Renames <one> to a new name <two>, together with its reflog
> 	and configuration settings ...

If you use <the-current-branch-or-a-named-branch> or something awkward like that as <one>, surely you can. But I do not think we want to go there. And neither <branch-name> or <old-branch> would remove the need for "if omitted then the current branch is used", I am afraid, even though there may be a way to rephrase it more concisely, e.g. "Rename the current branch (or <one> when given)..."

> Are we going to say "the current branch is used when ..." in the
> description for the other options too?  The description for "-c|-C",
> "--edit-description", "--unset-upstream", ...  Perhaps we are, and it
> will sound repetitive.

Do not forget that the objective of the larger-picture-revamping of this page is to make the description of each option self-contained. Similarity between -m's description and -c's description does not count as being uselessly repetitive.

Show 8 quoted lines

>> Even though the choice of words Rubén made in the patch under
>> discussion may work well in the current document structure.
>
> My patch is mainly about CodingGuideLines:
>
> 	If a placeholder has multiple words, they are separated by dashes:
> 	  <new-branch-name>
> 	  --template=<template-directory>

Yes, and that will be something we want to address _after_ we pick what word or phrase would replace <one> or <two> in the above at the conceptual level. If we picked a single word, say "branch", we do not even need to worry about dashes, and spell it just <branch>. If we did not pick "old branch", then we'd use "<old-branch>", but doing such a conversion based on the current text is a wasted work, if we end up using say "original branch" as the phrase, for example.

So if your patch is mainly about that part of the guideline, it is addressing the documentation update in a wrong order, creating possibly a wasted work.