git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / Atom feed
* [PATCH 0/8] Doc/submodules: a few updates
@ 2018-01-06 18:46 Kaartic Sivaraam
  2018-01-06 18:46 ` [PATCH 1/8] Doc/gitsubmodules: split a sentence for better readability Kaartic Sivaraam
                   ` (9 more replies)
  0 siblings, 10 replies; 44+ messages in thread
From: Kaartic Sivaraam @ 2018-01-06 18:46 UTC (permalink / raw)
  To: Git mailing list, Stefan Beller

These are just a few improvements that I thought would make the documentation
related to submodules a little better in various way such as readability,
consistency etc., These were things I noticed while reading thise documents.

Sorry, for the highly granular patches. I did the commits as and when I was
reading them and tried to keep them focused to one particular change by rebasing
them as needed. In case they need some change, let me know. 

I based these patches on top of 'master'.

Apart from the changes, I saw a few things that needed improvement/clarification
but wasn't able to do that myself due to my limited knowledge of submodules. They
are listed below. I'll add in patches for them if they are correctly clarified.


1.

 man gitsubmodules

       ·   The configuration file $GIT_DIR/config in the superproject. Typical configuration at this place is controlling if a submodule is
           recursed into at all via the active flag for example.

           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.

What's the "active flag" mentioned above? Also I find the phrase "is recursed into at all"
to be a little slippery. How could it be improved?


2.

 man git submodule

       update
           ...

           checkout
               ....

               If --force is specified, the submodule will be checked out (using git checkout --force if appropriate), even if the commit
               specified in the index of the containing repository already matches the commit checked out in the submodule.

I'm not sure this is conveying all the information it should be conveying.
It seems to making the user wonder, "How at all does 'git submodule update --force'
differs from 'git submodule update'?" also "using git checkout --force if appropriate"
seems to be invoking all sorts confusion as "appropriate" is superfluous.

How could these confusions be clarified?


---
Kaartic


Kaartic Sivaraam (8):
  Doc/gitsubmodules: split a sentence for better readability
  Doc/gitsubmodules: clearly specify advantage of submodule
  Doc/gitsubmodules: specify how submodules help in reduced size
  Doc/gitsubmodules: avoid abbreviations
  Doc/gitsubmodules: use "Git directory" consistently
  Doc/gitsubmodules: improve readability of certain lines
  Doc/git-submodule: improve readability and grammar of a sentence
  Doc/git-submodule: correctly quote important words

 Documentation/git-submodule.txt | 10 +++++-----
 Documentation/gitsubmodules.txt | 28 ++++++++++++++++------------
 2 files changed, 21 insertions(+), 17 deletions(-)

-- 
2.16.0.rc0.223.g4a4ac8367


^ permalink raw reply	[flat|nested] 44+ messages in thread

end of thread, back to index

Thread overview: 44+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2018-01-06 18:46 [PATCH 0/8] Doc/submodules: a few updates Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 1/8] Doc/gitsubmodules: split a sentence for better readability Kaartic Sivaraam
2018-01-07  0:29   ` Eric Sunshine
2018-01-08 18:33     ` Stefan Beller
2018-01-06 18:46 ` [PATCH 2/8] Doc/gitsubmodules: clearly specify advantage of submodule Kaartic Sivaraam
2018-01-08 18:36   ` Stefan Beller
2018-01-09 15:58     ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 3/8] Doc/gitsubmodules: specify how submodules help in reduced size Kaartic Sivaraam
2018-01-07  0:31   ` Eric Sunshine
2018-01-08 18:38   ` Stefan Beller
2018-01-09 16:01     ` Kaartic Sivaraam
2018-01-09 19:01       ` Stefan Beller
2018-01-09 19:30         ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 4/8] Doc/gitsubmodules: avoid abbreviations Kaartic Sivaraam
2018-01-07  0:36   ` Eric Sunshine
2018-01-08 18:45   ` Stefan Beller
2018-01-09 16:06     ` Kaartic Sivaraam
2018-01-09 19:26       ` Stefan Beller
2018-01-09 19:32         ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 5/8] Doc/gitsubmodules: use "Git directory" consistently Kaartic Sivaraam
2018-01-07  0:39   ` Eric Sunshine
2018-01-08 18:45     ` Stefan Beller
2018-01-06 18:46 ` [PATCH 6/8] Doc/gitsubmodules: improve readability of certain lines Kaartic Sivaraam
2018-01-07  0:44   ` Eric Sunshine
2018-01-08 18:49   ` Stefan Beller
2018-01-09 16:37     ` Kaartic Sivaraam
2018-01-09 19:31       ` Stefan Beller
2018-01-09 19:57         ` Kaartic Sivaraam
2018-01-06 18:46 ` [PATCH 7/8] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-08 18:57   ` Stefan Beller
2018-01-06 18:46 ` [PATCH 8/8] Doc/git-submodule: correctly quote important words Kaartic Sivaraam
2018-01-08 19:08 ` [PATCH 0/8] Doc/submodules: a few updates Stefan Beller
2018-01-09 17:06   ` Kaartic Sivaraam
2018-01-09 18:50     ` Stefan Beller
2018-01-10  6:49 ` [PATCH v2 0/2] " Kaartic Sivaraam
2018-01-10  6:49   ` [PATCH v2 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax Kaartic Sivaraam
2018-01-10 20:49     ` Stefan Beller
2018-01-10  6:49   ` [PATCH v2 2/2] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-14 17:37   ` [PATCH v3 0/2] Doc/submodules: a few updates Kaartic Sivaraam
2018-01-14 17:37     ` [PATCH v3 1/2] Doc/gitsubmodules: make some changes to improve readability and syntax Kaartic Sivaraam
2018-01-16 20:03       ` Stefan Beller
2018-01-14 17:37     ` [PATCH v3 2/2] Doc/git-submodule: improve readability and grammar of a sentence Kaartic Sivaraam
2018-01-16 20:02     ` [PATCH v3 0/2] Doc/submodules: a few updates Junio C Hamano
2018-01-17  2:45       ` Kaartic Sivaraam

git@vger.kernel.org list mirror (unofficial, one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Example config snippet for mirrors

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git