Re: [PATCH] doc: replace "--" with {litdd} in credential-cache/fsmonitor

From: Johannes Schindelin <johannes.schindelin@gmx.de>
Date: Apr 7, 2022, 13:33 UTC
Message-ID: <nycvar.QRO.7.76.6.2204071528590.347@tvgsbejvaqbjf.bet>
In-Reply-To: <20220406184122.4126898-1-tmz@pobox.com>

Hi Todd,

On Wed, 6 Apr 2022, Todd Zullinger wrote:

Show 13 quoted lines

> Asciidoc renders `--` as em-dash.  This is not appropriate for command
> names.  It also breaks linkgit links to these commands.
>
> Fix git-credential-cache--daemon and git-fsmonitor--daemon.  The latter
> was added 3248486920 (fsmonitor: document builtin fsmonitor, 2022-03-25)
> and included several links.  A check for broken links in the HTML docs
> turned this up.
>
> Manually inspecting the other Documentation/git-*--*.txt files turned up
> the issue in git-credential-cache--daemon.
>
> While here, quote `git credential-cache--daemon` in the synopsis to
> match the vast majority of our other documentation.

Looks very sensible.

While the credential--cache fix is technically not due to a regression in the 2.36.0 cycle, the fsmonitor--daemon one is, and it does not make sense to do only one during the -rc phase.

FWIW I just looked at https://git-scm.com/docs/git-credential-cache--daemon to verify that it indeed renders the double-dash as a long dash.

Show 18 quoted lines

> Signed-off-by: Todd Zullinger <tmz@pobox.com>
> ---
>  Documentation/config/core.txt                  |  2 +-
>  Documentation/git-credential-cache--daemon.txt |  6 +++---
>  Documentation/git-fsmonitor--daemon.txt        | 12 ++++++------
>  Documentation/git-update-index.txt             |  2 +-
>  4 files changed, 11 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt
> index 889522956e..e67392cc83 100644
> --- a/Documentation/config/core.txt
> +++ b/Documentation/config/core.txt
> @@ -63,7 +63,7 @@ core.protectNTFS::
>
>  core.fsmonitor::
>  	If set to true, enable the built-in file system monitor
> -	daemon for this working directory (linkgit:git-fsmonitor--daemon[1]).
> +	daemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]).

I am not quite certain that using `{litdd}` in a `linkgit` construct works both in AsciiDoc and AsciiDoctor, but I trust that you have verified that this works.

Thank you for doing this, Johannes

Show 65 quoted lines

>  +
>  Like hook-based file system monitors, the built-in file system monitor
>  can speed up Git commands that need to refresh the Git index
> diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt
> index 7051c6bdf8..01e1c214dd 100644
> --- a/Documentation/git-credential-cache--daemon.txt
> +++ b/Documentation/git-credential-cache--daemon.txt
> @@ -1,5 +1,5 @@
> -git-credential-cache--daemon(1)
> -===============================
> +git-credential-cache{litdd}daemon(1)
> +====================================
>
>  NAME
>  ----
> @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory
>  SYNOPSIS
>  --------
>  [verse]
> -git credential-cache--daemon [--debug] <socket>
> +'git credential-cache{litdd}daemon' [--debug] <socket>
>
>  DESCRIPTION
>  -----------
> diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt
> index 0fedf5a456..cc142fb861 100644
> --- a/Documentation/git-fsmonitor--daemon.txt
> +++ b/Documentation/git-fsmonitor--daemon.txt
> @@ -1,5 +1,5 @@
> -git-fsmonitor--daemon(1)
> -========================
> +git-fsmonitor{litdd}daemon(1)
> +=============================
>
>  NAME
>  ----
> @@ -8,10 +8,10 @@ git-fsmonitor--daemon - A Built-in File System Monitor
>  SYNOPSIS
>  --------
>  [verse]
> -'git fsmonitor--daemon' start
> -'git fsmonitor--daemon' run
> -'git fsmonitor--daemon' stop
> -'git fsmonitor--daemon' status
> +'git fsmonitor{litdd}daemon' start
> +'git fsmonitor{litdd}daemon' run
> +'git fsmonitor{litdd}daemon' stop
> +'git fsmonitor{litdd}daemon' status
>
>  DESCRIPTION
>  -----------
> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
> index 64315e2e8c..5ea2f2c60e 100644
> --- a/Documentation/git-update-index.txt
> +++ b/Documentation/git-update-index.txt
> @@ -528,7 +528,7 @@ This feature is intended to speed up git operations for repos that have
>  large working directories.
>
>  It enables git to work together with a file system monitor (see
> -linkgit:git-fsmonitor--daemon[1]
> +linkgit:git-fsmonitor{litdd}daemon[1]
>  and the
>  "fsmonitor-watchman" section of linkgit:githooks[5]) that can
>  inform it as to what files have been modified. This enables git to avoid
>