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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 13, 2019, 18:30 UTC
Message-ID: <xmqq4l97czhu.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <20190213081518.GA21926@archbookpro.localdomain>

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

Show 10 quoted lines

> 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.