Re: [PATCH] submodule documentation: Reorder introductory paragraphs

From: Stefan Beller <sbeller@google.com>
Date: May 26, 2015, 17:53 UTC
Message-ID: <CAGZ79kZHRRqKpSmnEfd7-UOL9QrPOhQYt7wsfaqGVTZkHc+mhQ@mail.gmail.com>
In-Reply-To: <xmqqfv6k9v1x.fsf@gitster.dls.corp.google.com>

On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 38 quoted lines

> Stefan Beller <sbeller@google.com> writes:
>
>>  DESCRIPTION
>>  -----------
>> +This command will inspect, update and manage submodules.
>>
>> +Submodules allow you to keep another Git repository in a subdirectory
>> +of your repository. The other repository has its own history,...
>
> The first line somehow bothered me, so I took a random sample of
> commands I often use:
>
>     git log
>        Shows the commit logs.
>
>     git show
>        Shows one or more objects (blobs, trees, tags and commits).
>
>     git commit
>        Stores the current contents of the index in a new commit along with a
>        log message from the user describing the changes.
>
>     git diff
>        Show changes between the working tree and the index or a tree, changes
>        between the index and a tree, changes between two trees, changes
>        between two blob objects, or changes between two files on disk.
>
>     git push
>        Updates remote refs using local refs, while sending objects necessary
>        to complete the given refs.
>
> I _think_ what bothered me was "This command" (drawing the reaction
> "eh, what other command are you going to talk about in the help page
> for this command?").  Perhaps
>
>     Inspects, updates and manages submodules.
>
> may match the style of other help pages better.

Sounds much better than my patch.

Show 11 quoted lines

>
> On the other hand, I probably would not have felt such a strong
> "strangeness" if it were described like this:
>
>     This command can help you inspect, update, and manage
>     submodules.
>
> I haven't analized it enough to say why it is, but I suspect it has
> something to do with (my own) perception that "git submodule" is not
> very essential to do any of these things (i.e. .gitmodules is a very
> simple text file), but is primarily a helpful wrapper.

My perception is that the submodule man page similar to the subtree man page tries to explain an underlying concept as well. The other man pages you quoted don't do that as the concepts are explained elsewhere(?)

As a side note: In the Gerrit test suite I use the JGit implementation of the config command to write out .gitmodules files. So maybe `git submodule` can be understood as a specialized form of `git config`.

Show 7 quoted lines

>
> The description of "git config", on which I have a similar
> perception, seem to match ;-)
>
>     git config
>        You can query/set/replace/unset options with this command.
>