patchgit-submodule.txt: document default behavior

This patch documents the default behavior of git-submodule if no subcommands are given, similar to how git-remote.txt documents it.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-submodule.txt | 3 +++
 1 file changed, 3 insertions(+)

On Tue, Feb 12, 2019 at 11:04 AM Denton Liu <liu.denton@gmail.com> wrote:

Maybe just "The default command is 'status'" and let the user read that subcommand for more info.

Thanks for the suggestion, Duy.

While I was fixing that up, I noticed a few other discrepancies so I decided to fix those up too.

Changes since v1:

* Incorporate Duy's suggestion of "The default command is '...'"
* Fix additional discrepancies between git-remote and git-submodule (on the
  submodule side)

Denton Liu (3):
  git-remote.txt: be specific about default behavior
  git-submodule.txt: make subcommands underlined
  submodule: document default behavior

 Documentation/git-remote.txt    |  4 ++--
 Documentation/git-submodule.txt | 22 +++++++++++++---------
 git-submodule.sh                |  3 ++-
 3 files changed, 17 insertions(+), 12 deletions(-)

Instead of beating around the bush, we directly specify the subcommand
that is called by default when none are provided. This way, a user will
know where to look for more information.
---
 Documentation/git-remote.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

In git-remote.txt, the subcommands are underlined. Following that, we
also underline the subcommands in git-submodule.txt.
---
 Documentation/git-submodule.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:

I'd like to retract this patch. I realised that between git-remote, git-submodule, git-notes, git-stash, git-bisect, git-reflog, it's pretty inconsistent between whether it's formatted with the underline or not.

Also, I missed the underlining of the subcommands in the body of the document.

But if someone thinks that unifying the formatting is a worthwhile pursuit, I'd be happy to reroll this patchset to include this fix.

Thanks,

Denton

On Wed, Feb 13, 2019 at 3:15 PM Denton Liu <liu.denton@gmail.com> wrote:

Making documents look consistent is always good, I think. If you want to do this, maybe have a look at the "Writing Documentation" section in CodingGuidelines and add a note there too, about quoting subcommand names.

Denton Liu <liu.denton@gmail.com> writes:

I actually do not think using '<emph>' inside the SYNOPSIS section is such a great idea to begin with. We do want `<literal>` mark-up in the body text to tell the users that it is something they need to type literally (as opposed to what they can substitute with their own).

In any case, consistent mark-up in the documentation is good. But you would probably want to make it a separate series, either a preparatory one before real content changes are made, or a cleanup one after.

Thanks.

This patch documents the default behavior of submodule if no subcommands are given, similar to how remote documents it in both git-remote.txt and in its usage output.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-submodule.txt | 4 ++++
 git-submodule.sh                | 3 ++-
 2 files changed, 6 insertions(+), 1 deletion(-)

Denton Liu <liu.denton@gmail.com> writes:

Let's stop saying "This patch does this, this patch does that".

Instead (1) state what you think is wrong with the status quo in the present tense, (2) describe what the right approach to make it better is and why, and (3) order the codebase to "be like so" to make that happen. Often (1) or (2) can be omitted when they are obvious from (3), but be mindful to others---the "obviousness" you may feel may come from your staring the problem longer and thinking about it deeper than the readers of your patch. When in doubt, err on the side of over-clarity.

    The SYNOPSIS section for 'git submodule' does not say what the
    command does when given no subcommand.  Document it.

does (1)+(3), which I think is sufficient.

I am not sure if "default is status" is really true.

   $ git submodule status --recursive
   $ git submodule --recursive
   usage: git submodule [--quiet] ...
      or: ...
   $ git submodule -- sha1collisiondetection
   usage: git submodule [--quiet] ...
      or: ...

If 'status' were truly the default, wouldn't the form without any subcommand take any option and parameter the 'status' subcommand would accept?

On Wed, Feb 13, 2019 at 10:39:48AM -0800, Junio C Hamano wrote:

This is very similar to git-remote. Its default command is 'show' but doing something like 'git remote -n' fails, even though 'git remote show -n' succeeds.

Would it make sense to revise this back to

	With no arguments, shows the status of existing submodules.

which was the phrasing I used in v1? (If this is the case, I'd also like to drop the first patch of this series.)

Thanks,

Denton

Denton Liu <liu.denton@gmail.com> writes:

It certainly would avoid spreading misinformation to the readers by technically more correct ;-). I wasn't paying close attention to the earlier round's review, but was there something specific that we wanted to achieve by mentioning "by default we do this"? If not, the "with no arguments ..." you have in your response is concise, readable, and informative and is a good description, I think.

Thanks.

Thanks for the review, Junio.

Changes since v1:

* Incorporate Duy's suggestion of "The default command is '...'"
* Fix additional discrepancies between git-remote and git-submodule (on the
  submodule side)

Changes since v2:

* Revert "The default command is '...'" back to original text
* Drop "git-remote.txt: be specific about default behavior" as a
  consequence of the above
* Drop "git-submodule.txt: make subcommands underlined" as this was
  unwanted

Denton Liu (1):
  submodule: document default behavior

 Documentation/git-submodule.txt | 4 ++++
 git-submodule.sh                | 3 ++-
 2 files changed, 6 insertions(+), 1 deletion(-)

submodule's default behavior wasn't documented in both git-submodule.txt and in the usage text of git-submodule. Document the default behavior similar to how git-remote does it.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---
 Documentation/git-submodule.txt | 4 ++++
 git-submodule.sh                | 3 ++-
 2 files changed, 6 insertions(+), 1 deletion(-)