| Message ID | 20220406184122.4126898-1-tmz@pobox.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | f3ea4bed2acb129db66c4c9a22dae71576d58066 |
| Headers | show |
| Series | doc: replace "--" with {litdd} in credential-cache/fsmonitor | expand |
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 >
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;
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.
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,
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!
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
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(-)