Re: [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines

[Kaartic Sivaraam <kaartic.sivaraam@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 3293 bytes --]

On Tuesday 09 January 2018 12:19 AM, Stefan Beller wrote:
> On Sat, Jan 6, 2018 at 10:46 AM, Kaartic Sivaraam
> <kaartic.sivaraam@gmail.com> wrote:
>>
>> - * The command line for those commands that support taking submodule
>> -   specifications. Most commands have a boolean flag '--recurse-submodules
>> -   whether to recurse into submodules. Examples are `ls-files` or `checkout`.
>> + * The command line arguments of those commands that support taking submodule
>> +   specifications. Most commands have a boolean flag '--recurse-submodules'
>> +   which specify whether they should recurse into submodules. Examples are
>> +   `ls-files` or `checkout`.
>>     Some commands take enums, such as `fetch` and `push`, where you can
>>     specify how submodules are affected.
>>
>> @@ -90,8 +91,8 @@ Submodule operations can be configured using the following mechanisms
>>  For example an effect from the submodule's `.gitignore` file
>>  would be observed when you run `git status --ignore-submodules=none` in
>>  the superproject. This collects information from the submodule's working
>> -directory by running `status` in the submodule, which does pay attention
>> -to its `.gitignore` file.
>> +directory by running `status` in the submodule while paying attention
>> +to the `.gitignore` file of the submodule.
> 
> Both are grammatically correct and expressive, thanks!
>

You're welcome!


>>  +
> 
> Extra spurious line?
>

No. That's a "real" plus in the document that's usually present between
paragraphs :) I think I now get why Junio suggests people to review
patches in context (possibly, by applying them) ;)


>>  The submodule's `$GIT_DIR/config` file would come into play when running
>>  `git push --recurse-submodules=check` in the superproject, as this would
>> @@ -107,13 +108,13 @@ If the submodule is not yet initialized, then the configuration
>>  inside the submodule does not exist yet, so configuration where to
>>  obtain the submodule from is configured here for example.
>>

I caught this in the context while replying. "so configuration where to
obtain the submodule from is configured here for example." doesn't seem
to read well. Maybe removing configuration from the sentence will make
it sound better?


>> - * the `.gitmodules` file inside the superproject. Additionally to the
>> -   required mapping between submodule's name and path, a project usually
>> + * The `.gitmodules` file inside the superproject. Additionally, if mapping
>> +   is required between a submodule's name and its path, a project usually
> 
> This changes meaning, originally it tries to say:
> 
> * it requires mapping path <-> names.

I get this ...

> * but there can be more.
> 

... but not this. Did the previous version really try to say this?
Anyways how does this sound?

  * The `.gitmodules` file inside the superproject. A project usually
    uses this file to suggest defaults for the upstream collection
    of repositories for the mapping that is required between a
    submodule's name and its path.

I think it conveys the "it requires mapping path <-> names." correctly
but doesn't convey the "but there can be more." part. I'm not sure how
to get that into the sentence, correctly.


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 870 bytes --]