{"thread":{"id":"57680","subject":"[PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor","startedAt":"2022-04-06T20:23:55Z","lastAt":"2022-04-07T18:37:29Z","messageCount":6,"participants":["Todd Zullinger","Johannes Schindelin","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"453217","messageId":"20220406184122.4126898-1-tmz@pobox.com","threadId":"57680","inReplyTo":null,"subject":"[PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2022-04-06T18:41:22Z","receivedAt":"2022-04-06T20:23:55Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Asciidoc renders `--` as em-dash.  This is not appropriate for command\nnames.  It also breaks linkgit links to these commands.\n\nFix git-credential-cache--daemon and git-fsmonitor--daemon.  The latter\nwas added 3248486920 (fsmonitor: document builtin fsmonitor, 2022-03-25)\nand included several links.  A check for broken links in the HTML docs\nturned this up.\n\nManually inspecting the other Documentation/git-*--*.txt files turned up\nthe issue in git-credential-cache--daemon.\n\nWhile here, quote `git credential-cache--daemon` in the synopsis to\nmatch the vast majority of our other documentation.\n\nSigned-off-by: Todd Zullinger <tmz@pobox.com>\n---\n Documentation/config/core.txt                  |  2 +-\n Documentation/git-credential-cache--daemon.txt |  6 +++---\n Documentation/git-fsmonitor--daemon.txt        | 12 ++++++------\n Documentation/git-update-index.txt             |  2 +-\n 4 files changed, 11 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/config/core.txt b/Documentation/config/core.txt\nindex 889522956e..e67392cc83 100644\n--- a/Documentation/config/core.txt\n+++ b/Documentation/config/core.txt\n@@ -63,7 +63,7 @@ core.protectNTFS::\n \n core.fsmonitor::\n \tIf set to true, enable the built-in file system monitor\n-\tdaemon for this working directory (linkgit:git-fsmonitor--daemon[1]).\n+\tdaemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]).\n +\n Like hook-based file system monitors, the built-in file system monitor\n can speed up Git commands that need to refresh the Git index\ndiff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\nindex 7051c6bdf8..01e1c214dd 100644\n--- a/Documentation/git-credential-cache--daemon.txt\n+++ b/Documentation/git-credential-cache--daemon.txt\n@@ -1,5 +1,5 @@\n-git-credential-cache--daemon(1)\n-===============================\n+git-credential-cache{litdd}daemon(1)\n+====================================\n \n NAME\n ----\n@@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n SYNOPSIS\n --------\n [verse]\n-git credential-cache--daemon [--debug] <socket>\n+'git credential-cache{litdd}daemon' [--debug] <socket>\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt\nindex 0fedf5a456..cc142fb861 100644\n--- a/Documentation/git-fsmonitor--daemon.txt\n+++ b/Documentation/git-fsmonitor--daemon.txt\n@@ -1,5 +1,5 @@\n-git-fsmonitor--daemon(1)\n-========================\n+git-fsmonitor{litdd}daemon(1)\n+=============================\n \n NAME\n ----\n@@ -8,10 +8,10 @@ git-fsmonitor--daemon - A Built-in File System Monitor\n SYNOPSIS\n --------\n [verse]\n-'git fsmonitor--daemon' start\n-'git fsmonitor--daemon' run\n-'git fsmonitor--daemon' stop\n-'git fsmonitor--daemon' status\n+'git fsmonitor{litdd}daemon' start\n+'git fsmonitor{litdd}daemon' run\n+'git fsmonitor{litdd}daemon' stop\n+'git fsmonitor{litdd}daemon' status\n \n DESCRIPTION\n -----------\ndiff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\nindex 64315e2e8c..5ea2f2c60e 100644\n--- a/Documentation/git-update-index.txt\n+++ b/Documentation/git-update-index.txt\n@@ -528,7 +528,7 @@ This feature is intended to speed up git operations for repos that have\n large working directories.\n \n It enables git to work together with a file system monitor (see\n-linkgit:git-fsmonitor--daemon[1]\n+linkgit:git-fsmonitor{litdd}daemon[1]\n and the\n \"fsmonitor-watchman\" section of linkgit:githooks[5]) that can\n inform it as to what files have been modified. This enables git to avoid\n"},{"id":"453259","messageId":"nycvar.QRO.7.76.6.2204071528590.347@tvgsbejvaqbjf.bet","threadId":"57680","inReplyTo":"20220406184122.4126898-1-tmz@pobox.com","subject":"Re: [PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2022-04-07T13:33:28Z","receivedAt":"2022-04-07T13:33:46Z","isPatch":true,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Todd,\n\nOn Wed, 6 Apr 2022, Todd Zullinger wrote:\n\n> Asciidoc renders `--` as em-dash.  This is not appropriate for command\n> names.  It also breaks linkgit links to these commands.\n>\n> Fix git-credential-cache--daemon and git-fsmonitor--daemon.  The latter\n> was added 3248486920 (fsmonitor: document builtin fsmonitor, 2022-03-25)\n> and included several links.  A check for broken links in the HTML docs\n> turned this up.\n>\n> Manually inspecting the other Documentation/git-*--*.txt files turned up\n> the issue in git-credential-cache--daemon.\n>\n> While here, quote `git credential-cache--daemon` in the synopsis to\n> match the vast majority of our other documentation.\n\nLooks very sensible.\n\nWhile the credential--cache fix is technically not due to a regression in\nthe 2.36.0 cycle, the fsmonitor--daemon one is, and it does not make sense\nto do only one during the -rc phase.\n\nFWIW I just looked at\nhttps://git-scm.com/docs/git-credential-cache--daemon to verify that it\nindeed renders the double-dash as a long dash.\n\n> Signed-off-by: Todd Zullinger <tmz@pobox.com>\n> ---\n>  Documentation/config/core.txt                  |  2 +-\n>  Documentation/git-credential-cache--daemon.txt |  6 +++---\n>  Documentation/git-fsmonitor--daemon.txt        | 12 ++++++------\n>  Documentation/git-update-index.txt             |  2 +-\n>  4 files changed, 11 insertions(+), 11 deletions(-)\n>\n> diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt\n> index 889522956e..e67392cc83 100644\n> --- a/Documentation/config/core.txt\n> +++ b/Documentation/config/core.txt\n> @@ -63,7 +63,7 @@ core.protectNTFS::\n>\n>  core.fsmonitor::\n>  \tIf set to true, enable the built-in file system monitor\n> -\tdaemon for this working directory (linkgit:git-fsmonitor--daemon[1]).\n> +\tdaemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]).\n\nI am not quite certain that using `{litdd}` in a `linkgit` construct works\nboth in AsciiDoc and AsciiDoctor, but I trust that you have verified that\nthis works.\n\nThank you for doing this,\nJohannes\n\n>  +\n>  Like hook-based file system monitors, the built-in file system monitor\n>  can speed up Git commands that need to refresh the Git index\n> diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt\n> index 7051c6bdf8..01e1c214dd 100644\n> --- a/Documentation/git-credential-cache--daemon.txt\n> +++ b/Documentation/git-credential-cache--daemon.txt\n> @@ -1,5 +1,5 @@\n> -git-credential-cache--daemon(1)\n> -===============================\n> +git-credential-cache{litdd}daemon(1)\n> +====================================\n>\n>  NAME\n>  ----\n> @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -git credential-cache--daemon [--debug] <socket>\n> +'git credential-cache{litdd}daemon' [--debug] <socket>\n>\n>  DESCRIPTION\n>  -----------\n> diff --git a/Documentation/git-fsmonitor--daemon.txt b/Documentation/git-fsmonitor--daemon.txt\n> index 0fedf5a456..cc142fb861 100644\n> --- a/Documentation/git-fsmonitor--daemon.txt\n> +++ b/Documentation/git-fsmonitor--daemon.txt\n> @@ -1,5 +1,5 @@\n> -git-fsmonitor--daemon(1)\n> -========================\n> +git-fsmonitor{litdd}daemon(1)\n> +=============================\n>\n>  NAME\n>  ----\n> @@ -8,10 +8,10 @@ git-fsmonitor--daemon - A Built-in File System Monitor\n>  SYNOPSIS\n>  --------\n>  [verse]\n> -'git fsmonitor--daemon' start\n> -'git fsmonitor--daemon' run\n> -'git fsmonitor--daemon' stop\n> -'git fsmonitor--daemon' status\n> +'git fsmonitor{litdd}daemon' start\n> +'git fsmonitor{litdd}daemon' run\n> +'git fsmonitor{litdd}daemon' stop\n> +'git fsmonitor{litdd}daemon' status\n>\n>  DESCRIPTION\n>  -----------\n> diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt\n> index 64315e2e8c..5ea2f2c60e 100644\n> --- a/Documentation/git-update-index.txt\n> +++ b/Documentation/git-update-index.txt\n> @@ -528,7 +528,7 @@ This feature is intended to speed up git operations for repos that have\n>  large working directories.\n>\n>  It enables git to work together with a file system monitor (see\n> -linkgit:git-fsmonitor--daemon[1]\n> +linkgit:git-fsmonitor{litdd}daemon[1]\n>  and the\n>  \"fsmonitor-watchman\" section of linkgit:githooks[5]) that can\n>  inform it as to what files have been modified. This enables git to avoid\n>\n"},{"id":"453278","messageId":"220407.86h774dcyk.gmgdl@evledraar.gmail.com","threadId":"57680","inReplyTo":"20220406184122.4126898-1-tmz@pobox.com","subject":"Re: [PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-04-07T17:23:26Z","receivedAt":"2022-04-07T17:28:14Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Apr 06 2022, Todd Zullinger wrote:\n\n> Asciidoc renders `--` as em-dash.  This is not appropriate for command\n> names.  It also breaks linkgit links to these commands.\n\nLooks good, for the linkgit case let's check it in \"make check-docs\":\n\ndiff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\nindex 1c61dd9512b..2f46b261282 100755\n--- a/Documentation/lint-gitlink.perl\n+++ b/Documentation/lint-gitlink.perl\n@@ -46,6 +46,7 @@ sub report {\n \t\tmy ($target, $page, $section) = ($1, $2, $3);\n \n \t\t# De-AsciiDoc\n+\t\tmy $raw_page = $page;\n \t\t$page =~ s/{litdd}/--/g;\n \n \t\tif (!exists $TXT{$page}) {\n@@ -61,6 +62,7 @@ sub report {\n \t\t\treport($pos, $line, $target, \"wrong section (should be $real_section)\");\n \t\t\tnext;\n \t\t}\n+\t\treport($pos, $line, $target, \"should link '--' as '{litdd}')\") if $raw_page =~ /--/;\n \t}\n \t# this resets our $. for each file\n \tclose ARGV if eof;\n"},{"id":"453280","messageId":"Yk8n6R33HrCCvSsP@pobox.com","threadId":"57680","inReplyTo":"nycvar.QRO.7.76.6.2204071528590.347@tvgsbejvaqbjf.bet","subject":"Re: [PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2022-04-07T18:05:29Z","receivedAt":"2022-04-07T18:11:18Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi Johannes,\n\nJohannes Schindelin wrote:\n> Hi Todd,\n>> diff --git a/Documentation/config/core.txt b/Documentation/config/core.txt\n>> index 889522956e..e67392cc83 100644\n>> --- a/Documentation/config/core.txt\n>> +++ b/Documentation/config/core.txt\n>> @@ -63,7 +63,7 @@ core.protectNTFS::\n>>\n>>  core.fsmonitor::\n>>  \tIf set to true, enable the built-in file system monitor\n>> -\tdaemon for this working directory (linkgit:git-fsmonitor--daemon[1]).\n>> +\tdaemon for this working directory (linkgit:git-fsmonitor{litdd}daemon[1]).\n> \n> I am not quite certain that using `{litdd}` in a `linkgit` construct works\n> both in AsciiDoc and AsciiDoctor, but I trust that you have verified that\n> this works.\n\nI did not do a build with asciidoc, but when I still built\nthe Fedora packages with asciidoc, we had already fixed\nsimilar issues with `{litdd}` and I don't believe that has\nchanged.  If it has, then we've got other broken links:\n\n    $ git grep 'linkgit:[^]]+\\{litdd\\}[^]]*\\[' -- Documentation/ | wc -l\n    8\n\n    $ git grep 'linkgit:[^]]+--[^]]*\\[' -- Documentation/ | wc -l\n    0\n\n> Thank you for doing this,\n\nAnd thank you for reviewing and testing.\n\n-- \nTodd\n"},{"id":"453281","messageId":"Yk8qU66OzzIEwDP4@pobox.com","threadId":"57680","inReplyTo":"220407.86h774dcyk.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2022-04-07T18:15:47Z","receivedAt":"2022-04-07T18:16:00Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Hi Ævar,\n\nÆvar Arnfjörð Bjarmason wrote:\n> Looks good, for the linkgit case let's check it in \"make check-docs\":\n> \n> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\n> index 1c61dd9512b..2f46b261282 100755\n> --- a/Documentation/lint-gitlink.perl\n> +++ b/Documentation/lint-gitlink.perl\n> @@ -46,6 +46,7 @@ sub report {\n>  \t\tmy ($target, $page, $section) = ($1, $2, $3);\n>  \n>  \t\t# De-AsciiDoc\n> +\t\tmy $raw_page = $page;\n>  \t\t$page =~ s/{litdd}/--/g;\n>  \n>  \t\tif (!exists $TXT{$page}) {\n> @@ -61,6 +62,7 @@ sub report {\n>  \t\t\treport($pos, $line, $target, \"wrong section (should be $real_section)\");\n>  \t\t\tnext;\n>  \t\t}\n> +\t\treport($pos, $line, $target, \"should link '--' as '{litdd}')\") if $raw_page =~ /--/;\n>  \t}\n>  \t# this resets our $. for each file\n>  \tclose ARGV if eof;\n\nExcellent, thanks!  I had run the lint-docs-gitlink target\nto see if it reported any issue, but it hadn't.  With this,\nprior to the change I made to git-update-index.txt, it\nproperly reports the issue:\n\n    make -C Documentation/ lint-docs-gitlink\n    ...\n\tLINT GITLINK git-update-index.txt\n    git-update-index.txt:531: error: git-fsmonitor--daemon[1]: should link '--' as '{litdd}'), shown with 'HERE' below:\n    git-update-index.txt:531:\t'linkgit:git-fsmonitor--daemon[1]' <-- HERE\n    make: *** [Makefile:442: .build/lint-docs/gitlink/git-update-index.ok] Error 1\n    make: *** Deleting file '.build/lint-docs/gitlink/git-update-index.ok'\n    make: Leaving directory '/src/git/Documentation'\n\nCheers,\n\n-- \nTodd\n"},{"id":"453283","messageId":"220407.86czhsd9jx.gmgdl@evledraar.gmail.com","threadId":"57680","inReplyTo":"Yk8qU66OzzIEwDP4@pobox.com","subject":"Re: [PATCH] doc: replace \"--\" with {litdd} in credential-cache/fsmonitor","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-04-07T18:35:53Z","receivedAt":"2022-04-07T18:37:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Apr 07 2022, Todd Zullinger wrote:\n\n> Hi Ævar,\n>\n> Ævar Arnfjörð Bjarmason wrote:\n>> Looks good, for the linkgit case let's check it in \"make check-docs\":\n>> \n>> diff --git a/Documentation/lint-gitlink.perl b/Documentation/lint-gitlink.perl\n>> index 1c61dd9512b..2f46b261282 100755\n>> --- a/Documentation/lint-gitlink.perl\n>> +++ b/Documentation/lint-gitlink.perl\n>> @@ -46,6 +46,7 @@ sub report {\n>>  \t\tmy ($target, $page, $section) = ($1, $2, $3);\n>>  \n>>  \t\t# De-AsciiDoc\n>> +\t\tmy $raw_page = $page;\n>>  \t\t$page =~ s/{litdd}/--/g;\n>>  \n>>  \t\tif (!exists $TXT{$page}) {\n>> @@ -61,6 +62,7 @@ sub report {\n>>  \t\t\treport($pos, $line, $target, \"wrong section (should be $real_section)\");\n>>  \t\t\tnext;\n>>  \t\t}\n>> +\t\treport($pos, $line, $target, \"should link '--' as '{litdd}')\") if $raw_page =~ /--/;\n>>  \t}\n>>  \t# this resets our $. for each file\n>>  \tclose ARGV if eof;\n>\n> Excellent, thanks!  I had run the lint-docs-gitlink target\n> to see if it reported any issue, but it hadn't.  With this,\n> prior to the change I made to git-update-index.txt, it\n> properly reports the issue:\n>\n>     make -C Documentation/ lint-docs-gitlink\n>     ...\n> \tLINT GITLINK git-update-index.txt\n>     git-update-index.txt:531: error: git-fsmonitor--daemon[1]: should link '--' as '{litdd}'), shown with 'HERE' below:\n>     git-update-index.txt:531:\t'linkgit:git-fsmonitor--daemon[1]' <-- HERE\n>     make: *** [Makefile:442: .build/lint-docs/gitlink/git-update-index.ok] Error 1\n>     make: *** Deleting file '.build/lint-docs/gitlink/git-update-index.ok'\n>     make: Leaving directory '/src/git/Documentation'\n\nYup, note that it'll find the other one(s) too if you pass the \"-k\" flag\nto make, i.e. it's erroring out and aborting on the first error (as is\nmake's default behavior).\n\nIt won't help with all the changes you made though, e.g. headers etc. We\ncould add that, but it would be bigger change. This seemed easy enough\nfor a proposed squash-in.\n\nThanks for the fix!\n"}]}