Re: [PATCH] branch: adjust documentation

From: Dragan Simic <dsimic@manjaro.org>
Date: Feb 29, 2024, 01:56 UTC
Message-ID: <2c4ade0e3403f9b346e088b894d722c4@manjaro.org>
In-Reply-To: <xmqqttlsld4t.fsf@gitster.g>

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

> Dragan Simic <dsimic@manjaro.org> writes:
>> 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!

Show 6 quoted lines

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

Show 17 quoted lines

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

Show 18 quoted lines

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

Show 9 quoted lines

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

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.

Show 10 quoted lines

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