Re: [PATCH] branch: adjust documentation

From: Rubén Justo <rjusto@gmail.com>
Date: Feb 29, 2024, 18:56 UTC
Message-ID: <cbaf17e7-37a6-4c2e-82ba-65fe41dd86b1@gmail.com>
In-Reply-To: <xmqqttlsld4t.fsf@gitster.g>

On Wed, Feb 28, 2024 at 09:20:02 -0800, Junio C Hamano wrote:

Show 15 quoted lines

> The current description section talks about option and its arguments
> without showing the syntax, making it unnecessarily extra verbose.
> For example, we see something like this:
> 
>     With a `-m` or `-M` option, <oldbranch> will be renamed to
>     <newbranch>.  If <oldbranch> had a corresponding reflog, it is
>     renamed to match ...
> 
> But in the final shape of the documentation, I would like to see the
> description section not talk about these arguments, and would read
> more like
> 
>     When given `-m` or `-M` options, the command renames an existing
>     branch to a different name.
>

Good.

Show 9 quoted lines

> among short descriptions made at the conceptual level on other modes
> like "listing" mode, "delete" mode, etc. [*3*] 
> 
> And the option description would become something like [*]:
> 
>     -m [<one>] <two>::
> 	Renames the branch <one> (the current branch is used when
> 	not given) to a new name <two>, together with its reflog and
> 	configuration settings for the branch. ...

> Now in such a context, <one> and <two> placeholders having actually
> the word "branch" in it would sound redundant and awkward to read,

Indeed.

But I'm on the fence.  Do we have to use "Renames the branch <one>"?

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

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. However, even if we do, with the _good enough_ placeholder the user will be able to fill the gaps we might leave in the documentation, like the one that presumably has bring us here: pull.1613.git.git.1701303891791.gitgitgadget@gmail.com.

And finally; Can't <one> and <two> be consistent with other bits we have in the documentation like the descriptions of "git switch <one>", "git checkout -b <two>" or "git init -b <three>"?

After the revamp, I'll be less happy (but happy :-) nonetheless) if we end up having a SYNOPSIS similar to the one we have today:

 - Documentation/git-branch.txt:
      'git branch' (-c | -C) [<one>] <two>
      'git branch' (-d | -D) [-r] <three>...
      'git branch' --edit-description [<three>]

It seems to me to be made up of disconnected pieces.

And for reference:

 - Documentation/git-switch.txt:
      'git switch' [<options>] [--no-guess] <four>
      'git switch' [<options>] --orphan <five>

 - Documentation/git-init.txt:
      'git init' [--initial-branch=<six>]

My apologies if I'm pushing too hard on this and being reiterative in my messages in this series. My intention has been to explore the use we want of the placeholders. Of course, this is not at odds with my sympathy for the vision proposed. I agree on the direction.

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