Re: [PATCH] branch: adjust documentation

Dragan Simic <dsimic@manjaro.org> writes:

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.

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

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.

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.

Thanks for pinging.

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

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

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

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

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

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