[v2,2/3] git-submodule.txt: make subcommands underlined

Commit Message

Denton Liu Feb. 12, 2019, 9:56 a.m. UTC

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(-)

Comments

Denton Liu Feb. 13, 2019, 8:15 a.m. UTC | #1

On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:
> In git-remote.txt, the subcommands are underlined. Following that, we
> also underline the subcommands in git-submodule.txt.

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

Duy Nguyen Feb. 13, 2019, 9:55 a.m. UTC | #2

On Wed, Feb 13, 2019 at 3:15 PM Denton Liu <[e-mail]> wrote:
>
> On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:
> > In git-remote.txt, the subcommands are underlined. Following that, we
> > also underline the subcommands in git-submodule.txt.
>
> 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.

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.

Junio C Hamano Feb. 13, 2019, 6:30 p.m. UTC | #3

Denton Liu <[e-mail]> writes:

> On Tue, Feb 12, 2019 at 01:56:11AM -0800, Denton Liu wrote:
>> In git-remote.txt, the subcommands are underlined. Following that, we
>> also underline the subcommands in git-submodule.txt.
>
> 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.

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.

Patch

diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt
index ba3c4df550..65a952fb96 100644
--- a/Documentation/git-submodule.txt
+++ b/Documentation/git-submodule.txt
@@ -9,15 +9,15 @@  git-submodule - Initialize, update or inspect submodules
 SYNOPSIS
 --------
 [verse]
-'git submodule' [--quiet] add [<options>] [--] <repository> [<path>]
-'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...]
-'git submodule' [--quiet] init [--] [<path>...]
-'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...)
-'git submodule' [--quiet] update [<options>] [--] [<path>...]
-'git submodule' [--quiet] summary [<options>] [--] [<path>...]
-'git submodule' [--quiet] foreach [--recursive] <command>
-'git submodule' [--quiet] sync [--recursive] [--] [<path>...]
-'git submodule' [--quiet] absorbgitdirs [--] [<path>...]
+'git submodule' [--quiet] 'add' [<options>] [--] <repository> [<path>]
+'git submodule' [--quiet] 'status' [--cached] [--recursive] [--] [<path>...]
+'git submodule' [--quiet] 'init' [--] [<path>...]
+'git submodule' [--quiet] 'deinit' [-f|--force] (--all|[--] <path>...)
+'git submodule' [--quiet] 'update' [<options>] [--] [<path>...]
+'git submodule' [--quiet] 'summary' [<options>] [--] [<path>...]
+'git submodule' [--quiet] 'foreach' [--recursive] <command>
+'git submodule' [--quiet] 'sync' [--recursive] [--] [<path>...]
+'git submodule' [--quiet] 'absorbgitdirs' [--] [<path>...]
 
 
 DESCRIPTION