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

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

[Todd Zullinger]

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.

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]).
 +
 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

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

[Johannes Schindelin]

Hi Todd,

On Wed, 6 Apr 2022, Todd Zullinger wrote:

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

> 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

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

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

[Todd Zullinger]

Hi Johannes,

Johannes Schindelin wrote:
> Hi Todd,
>> 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.

I did not do a build with asciidoc, but when I still built
the Fedora packages with asciidoc, we had already fixed
similar issues with `{litdd}` and I don't believe that has
changed.  If it has, then we've got other broken links:

    $ git grep 'linkgit:[^]]+\{litdd\}[^]]*\[' -- Documentation/ | wc -l
    8

    $ git grep 'linkgit:[^]]+--[^]]*\[' -- Documentation/ | wc -l
    0

> Thank you for doing this,

And thank you for reviewing and testing.

-- 
Todd

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

[Ævar Arnfjörð Bjarmason]

On Wed, Apr 06 2022, Todd Zullinger wrote:

> Asciidoc renders `--` as em-dash.  This is not appropriate for command
> names.  It also breaks linkgit links to these commands.

Looks good, for the linkgit case let's check it in "make check-docs":

diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
index 1c61dd9512b..2f46b261282 100755
--- a/Documentation/lint-gitlink.perl
+++ b/Documentation/lint-gitlink.perl
@@ -46,6 +46,7 @@ sub report {
 		my ($target, $page, $section) = ($1, $2, $3);
 
 		# De-AsciiDoc
+		my $raw_page = $page;
 		$page =~ s/{litdd}/--/g;
 
 		if (!exists $TXT{$page}) {
@@ -61,6 +62,7 @@ sub report {
 			report($pos, $line, $target, "wrong section (should be $real_section)");
 			next;
 		}
+		report($pos, $line, $target, "should link '--' as '{litdd}')") if $raw_page =~ /--/;
 	}
 	# this resets our $. for each file
 	close ARGV if eof;

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

[Todd Zullinger]

Hi Ævar,

Ævar Arnfjörð Bjarmason wrote:
> Looks good, for the linkgit case let's check it in "make check-docs":
> 
> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
> index 1c61dd9512b..2f46b261282 100755
> --- a/Documentation/lint-gitlink.perl
> +++ b/Documentation/lint-gitlink.perl
> @@ -46,6 +46,7 @@ sub report {
>  		my ($target, $page, $section) = ($1, $2, $3);
>  
>  		# De-AsciiDoc
> +		my $raw_page = $page;
>  		$page =~ s/{litdd}/--/g;
>  
>  		if (!exists $TXT{$page}) {
> @@ -61,6 +62,7 @@ sub report {
>  			report($pos, $line, $target, "wrong section (should be $real_section)");
>  			next;
>  		}
> +		report($pos, $line, $target, "should link '--' as '{litdd}')") if $raw_page =~ /--/;
>  	}
>  	# this resets our $. for each file
>  	close ARGV if eof;

Excellent, thanks!  I had run the lint-docs-gitlink target
to see if it reported any issue, but it hadn't.  With this,
prior to the change I made to git-update-index.txt, it
properly reports the issue:

    make -C Documentation/ lint-docs-gitlink
    ...
	LINT GITLINK git-update-index.txt
    git-update-index.txt:531: error: git-fsmonitor--daemon[1]: should link '--' as '{litdd}'), shown with 'HERE' below:
    git-update-index.txt:531:	'linkgit:git-fsmonitor--daemon[1]' <-- HERE
    make: *** [Makefile:442: .build/lint-docs/gitlink/git-update-index.ok] Error 1
    make: *** Deleting file '.build/lint-docs/gitlink/git-update-index.ok'
    make: Leaving directory '/src/git/Documentation'

Cheers,

-- 
Todd

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

[Ævar Arnfjörð Bjarmason]

On Thu, Apr 07 2022, Todd Zullinger wrote:

> Hi Ævar,
>
> Ævar Arnfjörð Bjarmason wrote:
>> Looks good, for the linkgit case let's check it in "make check-docs":
>> 
>> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl
>> index 1c61dd9512b..2f46b261282 100755
>> --- a/Documentation/lint-gitlink.perl
>> +++ b/Documentation/lint-gitlink.perl
>> @@ -46,6 +46,7 @@ sub report {
>>  		my ($target, $page, $section) = ($1, $2, $3);
>>  
>>  		# De-AsciiDoc
>> +		my $raw_page = $page;
>>  		$page =~ s/{litdd}/--/g;
>>  
>>  		if (!exists $TXT{$page}) {
>> @@ -61,6 +62,7 @@ sub report {
>>  			report($pos, $line, $target, "wrong section (should be $real_section)");
>>  			next;
>>  		}
>> +		report($pos, $line, $target, "should link '--' as '{litdd}')") if $raw_page =~ /--/;
>>  	}
>>  	# this resets our $. for each file
>>  	close ARGV if eof;
>
> Excellent, thanks!  I had run the lint-docs-gitlink target
> to see if it reported any issue, but it hadn't.  With this,
> prior to the change I made to git-update-index.txt, it
> properly reports the issue:
>
>     make -C Documentation/ lint-docs-gitlink
>     ...
> 	LINT GITLINK git-update-index.txt
>     git-update-index.txt:531: error: git-fsmonitor--daemon[1]: should link '--' as '{litdd}'), shown with 'HERE' below:
>     git-update-index.txt:531:	'linkgit:git-fsmonitor--daemon[1]' <-- HERE
>     make: *** [Makefile:442: .build/lint-docs/gitlink/git-update-index.ok] Error 1
>     make: *** Deleting file '.build/lint-docs/gitlink/git-update-index.ok'
>     make: Leaving directory '/src/git/Documentation'

Yup, note that it'll find the other one(s) too if you pass the "-k" flag
to make, i.e. it's erroring out and aborting on the first error (as is
make's default behavior).

It won't help with all the changes you made though, e.g. headers etc. We
could add that, but it would be bigger change. This seemed easy enough
for a proposed squash-in.

Thanks for the fix!