Re: [PATCH] branch: adjust documentation

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

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

> 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.

>> 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.