git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Denton Liu <liu.denton@gmail.com>
To: Git Mailing List <git@vger.kernel.org>
Cc: Junio C Hamano <gitster@pobox.com>
Subject: [PATCH v2] git-submodule.txt: fix AsciiDoc formatting error
Date: Mon, 16 Sep 2019 11:19:17 -0700	[thread overview]
Message-ID: <2ae16375ba185bcaceb2ba3e8843db495f0044a6.1568657575.git.liu.denton@gmail.com> (raw)
In-Reply-To: <796a25ee1e9a9c0421d42ab6644e81d23a9bd99b.1568142486.git.liu.denton@gmail.com>

In b57e8119e6 (submodule: teach set-branch subcommand, 2019-02-08), the
`set-branch` subcommand was added for submodules. When the documentation
was written, the syntax for a "index term" in AsciiDoc was
accidentally used. This caused the documentation to be rendered as

	set-branch -d|--default)|(-b|--branch <branch> [--] <path>

instead of

	set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>

In addition to this, the original documentation was possibly confusing
as it made it seem as if the `-b` option didn't accept a `<branch>`
argument.

Break `--default` and `--branch` into their own separate invocations to
make it obvious that these options are mutually exclusive. Also, this
removes the surrounding parentheses so that the "index term" syntax is
not triggered.

Signed-off-by: Denton Liu <liu.denton@gmail.com>
---

Thanks for reviewing, Junio.

I thought about it over the weekend and I hope that this is a good
compromise.

I looked through other options in the documentation and I couldn't find
any other places where a short-form was documented in the body instead
of in the summary line so I didn't want to introduce that with this
commit. I feel like it would be unfamiliar to someone who's used to
reading other Git documentation.

Also, I opted to separate the the options onto their own lines because
this makes it obvious that these two arguments are incompatible.
Hopefully, this assuages your concerns.

Range-diff against v1:
1:  796a25ee1e ! 1:  2ae16375ba git-submodule.txt: fix AsciiDoc formatting error
    @@ Commit message
     
         instead of
     
    -            set-branch (-d|--default)|(-b|--branch <branch>) [--] <path>
    +            set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>
     
    -    Remove surrounding parentheses so that the "index term" syntax is not
    -    triggered (and because it looks nicer without them anyway ;) ).
    +    In addition to this, the original documentation was possibly confusing
    +    as it made it seem as if the `-b` option didn't accept a `<branch>`
    +    argument.
    +
    +    Break `--default` and `--branch` into their own separate invocations to
    +    make it obvious that these options are mutually exclusive. Also, this
    +    removes the surrounding parentheses so that the "index term" syntax is
    +    not triggered.
     
         Signed-off-by: Denton Liu <liu.denton@gmail.com>
     
    @@ Documentation/git-submodule.txt: submodule with the `--init` option.
      registered submodules, and update any nested submodules within.
      --
     -set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>::
    -+set-branch (-d|--default)|(-b|--branch <branch>) [--] <path>::
    ++set-branch (-b|--branch) <branch> [--] <path>::
    ++set-branch (-d|--default) [--] <path>::
      	Sets the default remote tracking branch for the submodule. The
      	`--branch` option allows the remote branch to be specified. The
      	`--default` option removes the submodule.<name>.branch configuration

 Documentation/git-submodule.txt | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index 0ed5c24dc1..1f46380af2 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -173,7 +173,8 @@ submodule with the `--init` option.
 If `--recursive` is specified, this command will recurse into the
 registered submodules, and update any nested submodules within.
 --
-set-branch ((-d|--default)|(-b|--branch <branch>)) [--] <path>::
+set-branch (-b|--branch) <branch> [--] <path>::
+set-branch (-d|--default) [--] <path>::
 	Sets the default remote tracking branch for the submodule. The
 	`--branch` option allows the remote branch to be specified. The
 	`--default` option removes the submodule.<name>.branch configuration
-- 
2.23.0


  parent reply	other threads:[~2019-09-16 18:19 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-10 19:09 [PATCH] git-submodule.txt: fix AsciiDoc formatting error Denton Liu
2019-09-13 18:03 ` Junio C Hamano
2019-09-13 22:09   ` Denton Liu
2019-09-13 23:13     ` Junio C Hamano
2019-09-16 18:19 ` Denton Liu [this message]
2019-09-16 19:25   ` [PATCH v2] " Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=2ae16375ba185bcaceb2ba3e8843db495f0044a6.1568657575.git.liu.denton@gmail.com \
    --to=liu.denton@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).