On 2024-02-28 18:20, Junio C Hamano wrote:

Dragan Simic [off-list ref] writes:

quoted

Just checking, do you see the changes that Ruben proposed in this 
patch
fit for our starting point in the git-branch documentation rewrite?

First of all, I _really_ appreciate your highly detailed feedback.
Thank you very much for taking the time to write it all down!

The synopsis part may, but with reservations.  I know you two are
aiming to make this in many small incremental steps, but even then
I'd have to say the way these placeholder words will be used in the
text part (both DESCRIPTION and OPTIONS) will be so different from
the final shape envisioned [*1*], the wording that may fit well within
the current text might not be the best fit in the final text.

Please, let me remind you that I've already agreed upon doing it all
in one fell swoop, which may consist of multiple patches in a series,
but applied as a whole.

The current description section talks about option and its arguments
without showing the syntax, making it unnecessary to be 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.

among short descriptions made at the conceptual level on other modes
like "listing" mode, "delete" mode, etc. [*3*]

I agree on that being the final outcome, because the descriptions
of arguments actually belong to the envisioned "OPTIONS" section,
as part of the command descriptions.

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

    Side note: <one> and <two> are meta-placeholders for the purpose
    of this document; Ruben's patch proposes to call them <branch>
    and <new-branch>.

Now in such a context, <one> and <two> placeholders having actually
the word "branch" in it would sound redundant and awkward to read,
Even though the choice of words Ruben made in the patch under
discussion may work well in the current document structure.  I
suspect these words will have to be chosen again when we start
making the real organizational changes to the description and
options sections.

Well, perhaps it's the best to revisit the argument naming later.

In other words, I do not think that the patch makes an effective
"one good step in the right direction".  At least, I couldn't see
how the wording for placeholders the patch proposes to use would be
helpful in deciding the placeholders used in the final version.

I see, thanks for the clarification.

[Footnotes]

 *1* Do we share the vision on how the final version should look
     like?  Here I am assuming "the final shape envisioned" is along
     the lines of [*2*], i.e.

     (1) trim descriptions to just enumerate different modes of
         operations with explanation on what they do at the
         conceptual level;

Yes, that's also how I see it.  The "DESCRIPTION" sections should
end up describing only the available different modes.

     (2) make each entry in the options section self contained, by
         showing the option with their <argument>s, referring to
         them in the explanation text;

Agreed once again.  The "OPTIONS" section should end up describing
the available options, together with their respective arguments, in
a way that doesn't require the reader to jump to other places in the
document to fully understand each of the options.

     (3) remove non-option <argument> from the options list.

Yes, that goes along with the descriptions being self-contained.

 *2* https://lore.kernel.org/git/xmqqttmmlahf.fsf@gitster.g/ (local)

Sure, I already went through your message linked above, which already
described it quite well.

 *3* Because "git branch" does so many things, the DESCRIPTION
     section should first say the purpose of the section is to serve
     as brief catalog of features to help readers to find the entry
     in the option section to jump to quickly.  Something like:

Yup, as I already explained it above.  To reiterate, the purpose of
the "DESCRIPTION" section is to let the reader know what git-branch
can do, in form of easily readable prose.

     The "git branch" command works in many modes (see SYNOPSIS
     above).  By default the command works in the "list" option (the
     `--list` option explicitly asks for this mode).

     will be at the beginning of the section.  The first four
     paragraphs in the current DESCRIPTION section is about this
     list mode.  The first three of them should probably be moved to
     the OPTIONS section under `--list`.  The fourth paragraph
     should be split and described in the entries of individual
     options it talks about in the OPTIONS section.

Agreed, once again. :)  Most of the prose currently found in the
"DESCRIPTION" section should actually be moved to the various command
descriptions in the envisioned future "OPTIONS" section.