{"thread":{"id":"62729","subject":"[PATCH 0/2] documentation fixes for 2.48.0","startedAt":"2025-01-03T11:34:02Z","lastAt":"2025-01-03T16:21:45Z","messageCount":6,"participants":["Martin Ågren","Eric Sunshine","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":2},"messages":[{"id":"509835","messageId":"cover.1735903029.git.martin.agren@gmail.com","threadId":"62729","inReplyTo":null,"subject":"[PATCH 0/2] documentation fixes for 2.48.0","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2025-01-03T11:33:29Z","receivedAt":"2025-01-03T11:34:02Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"These two patches fix some misrenderings of the built documentation,\nintroduced during the 2.48 cycle. As usual, the exact current behaviors\n(symptoms) differ a bit between AsciiDoc and Asciidoctor.\n\nMartin\n\nMartin Ågren (2):\n git.txt: fix heading line of tildes\n gitcli.txt: typeset pathnames as monospace\n\n Documentation/git.txt | 2 +-\n Documentation/gitcli.txt | 2 +-\n 2 files changed, 2 insertions(+), 2 deletions(-)\n\n-- \n2.48.0.rc1.241.g6c04ab211c\n\n"},{"id":"509836","messageId":"50e47d14a8a0a2ca0dd158f01b833a28c7b46887.1735903029.git.martin.agren@gmail.com","threadId":"62729","inReplyTo":"cover.1735903029.git.martin.agren@gmail.com","subject":"[PATCH 1/2] git.txt: fix heading line of tildes","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2025-01-03T11:33:30Z","receivedAt":"2025-01-03T11:34:05Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"The two-line heading added in 8525e92886 (Document HOME environment\nvariable, 2024-12-09) uses too many tilde characters, so the heading\nisn't detected as such. Both AsciiDoc and Asciidoctor end up\nmisrendering this in different ways.\n\nUse the correct number of tilde characters to fix this.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/git.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 81498393af..e89a91dd0d 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -478,7 +478,7 @@ their values the same way as Boolean valued configuration variables, e.g.\n Here are the variables:\n \n System\n-~~~~~~~~~~~~~~~~~~\n+~~~~~~\n `HOME`::\n \tSpecifies the path to the user's home directory. On Windows, if\n \tunset, Git will set a process environment variable equal to:\n-- \n2.48.0.rc1.241.g6c04ab211c\n\n"},{"id":"509837","messageId":"6e0abe96b60a94d4fdee15a45b7d53c2f44a0c69.1735903029.git.martin.agren@gmail.com","threadId":"62729","inReplyTo":"cover.1735903029.git.martin.agren@gmail.com","subject":"[PATCH 2/2] gitcli.txt: typeset pathnames as monospace","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2025-01-03T11:33:31Z","receivedAt":"2025-01-03T11:34:07Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"Commit 1bc1e94091 (doc: option value may be separate for valid reasons,\n2024-11-25) added a paragraph discussing tilde-expansion of, e.g.,\n~/directory/file.\n\nThe tilde character has a special meaning to asciidoc tools. In this\nparticular case, AsciiDoc matches up the two tildes in \"e.g.\n~/directory/file or ~u/d/f\" and sets the text between them using\nsubscript. In the manpage, where subscripting is not possible, this\nrenders as \"e.g. /directory/file oru/d/f\".\n\nThese paths are literal values, which our coding guidelines want typeset\nas verbatim using backticks. Do that. One effect of this is indeed that\nthe asciidoc tools stop interpreting tilde and other special characters.\n\nSigned-off-by: Martin Ågren \n---\n Documentation/gitcli.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt\nindex bd62cbd043..fcd86d2eee 100644\n--- a/Documentation/gitcli.txt\n+++ b/Documentation/gitcli.txt\n@@ -91,7 +91,7 @@ scripting Git:\n written in the 'stuck' form.\n \n * Despite the above suggestion, when Arg is a path relative to the\n- home directory of a user, e.g. ~/directory/file or ~u/d/f, you\n+ home directory of a user, e.g. `~/directory/file` or `~u/d/f`, you\n may want to use the separate form, e.g. `git foo --file ~/mine`,\n not `git foo --file=~/mine`. The shell will expand `~/` in the\n former to your home directory, but most shells keep the tilde in\n-- \n2.48.0.rc1.241.g6c04ab211c\n\n"},{"id":"509838","messageId":"CAPig+cQoFC_2M-S0d7SLBPFvusXQC93pbk3QP2+qhsa7BJGnuQ@mail.gmail.com","threadId":"62729","inReplyTo":"cover.1735903029.git.martin.agren@gmail.com","subject":"Re: [PATCH 0/2] documentation fixes for 2.48.0","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2025-01-03T11:39:21Z","receivedAt":"2025-01-03T11:39:33Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Fri, Jan 3, 2025 at 6:34 AM Martin Ågren wrote:\n> These two patches fix some misrenderings of the built documentation,\n> introduced during the 2.48 cycle. As usual, the exact current behaviors\n> (symptoms) differ a bit between AsciiDoc and Asciidoctor.\n\nBoth patches make sense. Out of curiosity, how are you discovering\nthese problems? Are you, for instance, running doc-diff and manually\nscanning the output?\n"},{"id":"509840","messageId":"CAN0heSqKsAoeQdhUhP1fK8V3H2Xi=UeoHGM1GH-=QdysC99qwA@mail.gmail.com","threadId":"62729","inReplyTo":"CAPig+cQoFC_2M-S0d7SLBPFvusXQC93pbk3QP2+qhsa7BJGnuQ@mail.gmail.com","subject":"Re: [PATCH 0/2] documentation fixes for 2.48.0","fromName":"Martin Ågren","fromEmail":"martin.agren@gmail.com","sentAt":"2025-01-03T11:59:08Z","receivedAt":"2025-01-03T11:59:21Z","isPatch":true,"sender":{"key":"martin.agren@gmail.com","avatar":null},"body":"On Fri, 3 Jan 2025 at 12:39, Eric Sunshine wrote:\n>\n> On Fri, Jan 3, 2025 at 6:34 AM Martin Ågren wrote:\n> > These two patches fix some misrenderings of the built documentation,\n> > introduced during the 2.48 cycle. As usual, the exact current behaviors\n> > (symptoms) differ a bit between AsciiDoc and Asciidoctor.\n>\n> Both patches make sense. Out of curiosity, how are you discovering\n> these problems? Are you, for instance, running doc-diff and manually\n> scanning the output?\n\nYes, exactly. Something like\n\n ./doc-diff v2.47.0 v2.48.0-rc1\n\nis a nice way of finding out what's new. Occasionally, some oddity like\nthese stick out.\n\n(The diff can easily look huge, but often several pages contain the same\ncontent, so the 2nd/3rd/4th/... instance of a particular diff can be\nskipped. Inclusion of diff-options.txt would be the typical example.)\n\nMartin\n"},{"id":"509864","messageId":"xmqqjzbbswa0.fsf@gitster.g","threadId":"62729","inReplyTo":"cover.1735903029.git.martin.agren@gmail.com","subject":"Re: [PATCH 0/2] documentation fixes for 2.48.0","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-01-03T16:21:43Z","receivedAt":"2025-01-03T16:21:45Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin Ågren writes:\n\n> These two patches fix some misrenderings of the built documentation,\n> introduced during the 2.48 cycle. As usual, the exact current behaviors\n> (symptoms) differ a bit between AsciiDoc and Asciidoctor.\n\nThanks.\n"}]}