{"thread":{"id":"64272","subject":"[PATCH] doc: fix accidental literal blocks","startedAt":"2025-10-08T11:49:27Z","lastAt":"2025-10-10T09:38:18Z","messageCount":4,"participants":["kristofferhaugsbakk@fastmail.com","Jeff King","Kristoffer Haugsbakk"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"528237","messageId":"7a955ecb1b5.1759923933.git.code@khaugsbakk.name","threadId":"64272","inReplyTo":null,"subject":"[PATCH] doc: fix accidental literal blocks","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-08T11:48:46Z","receivedAt":"2025-10-08T11:49:27Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nMake sure that normal paragraphs in most user-facing docs[1] don’t\nuse literal blocks. This can easily happen if you try to maintain\nindentation in order to continue a block; that might work in\ne.g. Markdown variants, but not in AsciiDoc.\n\nThe fixes are straightforward, i.e. just deindent the block and maybe\nadd line continuations. The only exception is git-sparse-checkout(1)\nwhere we also replace indentation used for *intended* literal blocks\nwith `----`.\n\n† 1: These have not been considered:\n     • `Documentation/howto/`\n     • `Documentation/technical/`\n     • `Documentation/gitprotocol*`\n\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    I have noticed and sent patches for these things in the past because I\n    randomly spotted them, more or less.  This time though I have tried to\n    go through the docs and actively look for them.  These should be the\n    only ones if my hunting approach was sound.\n    \n    About not considering those other docs:\n    \n    In general, the *technical* documentation has worse HTML output than the\n    more user-facing docs, to the point where it looks like they might not\n    have been written with output formats/publishing in mind. So there might\n    not be a point to fixing them.\n    \n    I could have fixed one paragraph in gitprotocol-v2 but then that raises\n    the question of what about the other paragraphs? That in turn made the\n    commit message too long just for that point so I dropped it.\n\n Documentation/config/core.adoc         |  4 +-\n Documentation/git-config.adoc          | 18 +++----\n Documentation/git-rev-parse.adoc       | 14 ++---\n Documentation/git-shortlog.adoc        |  4 +-\n Documentation/git-sparse-checkout.adoc | 72 ++++++++++++++++----------\n 5 files changed, 64 insertions(+), 48 deletions(-)\n\ndiff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc\nindex 3fbe83eef16..8866ed27714 100644\n--- a/Documentation/config/core.adoc\n+++ b/Documentation/config/core.adoc\n@@ -75,8 +75,8 @@ The built-in file system monitor is currently available only on a\n limited set of supported platforms.  Currently, this includes Windows\n and MacOS.\n +\n-\tOtherwise, this variable contains the pathname of the \"fsmonitor\"\n-\thook command.\n+Otherwise, this variable contains the pathname of the \"fsmonitor\"\n+hook command.\n +\n This hook command is used to identify all files that may have changed\n since the requested date/time. This information is used to speed up\ndiff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc\nindex 511b2e26bfb..a633ab8ec3a 100644\n--- a/Documentation/git-config.adoc\n+++ b/Documentation/git-config.adoc\n@@ -117,15 +117,15 @@ OPTIONS\n \n --comment <message>::\n \tAppend a comment at the end of new or modified lines.\n-\n-\tIf _<message>_ begins with one or more whitespaces followed\n-\tby \"#\", it is used as-is.  If it begins with \"#\", a space is\n-\tprepended before it is used.  Otherwise, a string \" # \" (a\n-\tspace followed by a hash followed by a space) is prepended\n-\tto it.  And the resulting string is placed immediately after\n-\tthe value defined for the variable.  The _<message>_ must\n-\tnot contain linefeed characters (no multi-line comments are\n-\tpermitted).\n++\n+If _<message>_ begins with one or more whitespaces followed\n+by \"#\", it is used as-is.  If it begins with \"#\", a space is\n+prepended before it is used.  Otherwise, a string \" # \" (a\n+space followed by a hash followed by a space) is prepended\n+to it.  And the resulting string is placed immediately after\n+the value defined for the variable.  The _<message>_ must\n+not contain linefeed characters (no multi-line comments are\n+permitted).\n \n --all::\n \tWith `get`, return all values for a multi-valued key.\ndiff --git a/Documentation/git-rev-parse.adoc b/Documentation/git-rev-parse.adoc\nindex cc32b4b4f0f..18383e52af7 100644\n--- a/Documentation/git-rev-parse.adoc\n+++ b/Documentation/git-rev-parse.adoc\n@@ -174,13 +174,13 @@ for another option.\n \n \tAllow oids to be input from any object format that the current\n \trepository supports.\n-\n-\tSpecifying \"sha1\" translates if necessary and returns a sha1 oid.\n-\n-\tSpecifying \"sha256\" translates if necessary and returns a sha256 oid.\n-\n-\tSpecifying \"storage\" translates if necessary and returns an oid in\n-\tencoded in the storage hash algorithm.\n++\n+Specifying \"sha1\" translates if necessary and returns a sha1 oid.\n++\n+Specifying \"sha256\" translates if necessary and returns a sha256 oid.\n++\n+Specifying \"storage\" translates if necessary and returns an oid in\n+encoded in the storage hash algorithm.\n \n Options for Objects\n ~~~~~~~~~~~~~~~~~~~\ndiff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc\nindex d8ab38dcc1f..aa92800c69c 100644\n--- a/Documentation/git-shortlog.adoc\n+++ b/Documentation/git-shortlog.adoc\n@@ -44,8 +44,8 @@ OPTIONS\n \tdescribe each commit.  '<format>' can be any string accepted\n \tby the `--format` option of 'git log', such as '* [%h] %s'.\n \t(See the \"PRETTY FORMATS\" section of linkgit:git-log[1].)\n-\n-\tEach pretty-printed commit will be rewrapped before it is shown.\n++\n+Each pretty-printed commit will be rewrapped before it is shown.\n \n --date=<format>::\n \tShow dates formatted according to the given date string. (See\ndiff --git a/Documentation/git-sparse-checkout.adoc b/Documentation/git-sparse-checkout.adoc\nindex 529a8edd9c1..b5fe5da0416 100644\n--- a/Documentation/git-sparse-checkout.adoc\n+++ b/Documentation/git-sparse-checkout.adoc\n@@ -264,34 +264,50 @@ patterns in non-cone mode has a number of shortcomings:\n     inconsistent.\n \n   * It has edge cases where the \"right\" behavior is unclear.  Two examples:\n-\n-    First, two users are in a subdirectory, and the first runs\n-       git sparse-checkout set '/toplevel-dir/*.c'\n-    while the second runs\n-       git sparse-checkout set relative-dir\n-    Should those arguments be transliterated into\n-       current/subdirectory/toplevel-dir/*.c\n-    and\n-       current/subdirectory/relative-dir\n-    before inserting into the sparse-checkout file?  The user who typed\n-    the first command is probably aware that arguments to set/add are\n-    supposed to be patterns in non-cone mode, and probably would not be\n-    happy with such a transliteration.  However, many gitignore-style\n-    patterns are just paths, which might be what the user who typed the\n-    second command was thinking, and they'd be upset if their argument\n-    wasn't transliterated.\n-\n-    Second, what should bash-completion complete on for set/add commands\n-    for non-cone users?  If it suggests paths, is it exacerbating the\n-    problem above?  Also, if it suggests paths, what if the user has a\n-    file or directory that begins with either a '!' or '#' or has a '*',\n-    '\\', '?', '[', or ']' in its name?  And if it suggests paths, will\n-    it complete \"/pro\" to \"/proc\" (in the root filesystem) rather than to\n-    \"/progress.txt\" in the current directory?  (Note that users are\n-    likely to want to start paths with a leading '/' in non-cone mode,\n-    for the same reason that .gitignore files often have one.)\n-    Completing on files or directories might give nasty surprises in\n-    all these cases.\n++\n+First, two users are in a subdirectory, and the first runs\n++\n+----\n+git sparse-checkout set '/toplevel-dir/*.c'\n+----\n++\n+while the second runs\n++\n+----\n+git sparse-checkout set relative-dir\n+----\n++\n+Should those arguments be transliterated into\n++\n+----\n+current/subdirectory/toplevel-dir/*.c\n+----\n++\n+and\n++\n+----\n+current/subdirectory/relative-dir\n+----\n++\n+before inserting into the sparse-checkout file?  The user who typed\n+the first command is probably aware that arguments to set/add are\n+supposed to be patterns in non-cone mode, and probably would not be\n+happy with such a transliteration.  However, many gitignore-style\n+patterns are just paths, which might be what the user who typed the\n+second command was thinking, and they'd be upset if their argument\n+wasn't transliterated.\n++\n+Second, what should bash-completion complete on for set/add commands\n+for non-cone users?  If it suggests paths, is it exacerbating the\n+problem above?  Also, if it suggests paths, what if the user has a\n+file or directory that begins with either a '!' or '#' or has a '*',\n+'\\', '?', '[', or ']' in its name?  And if it suggests paths, will\n+it complete \"/pro\" to \"/proc\" (in the root filesystem) rather than to\n+\"/progress.txt\" in the current directory?  (Note that users are\n+likely to want to start paths with a leading '/' in non-cone mode,\n+for the same reason that .gitignore files often have one.)\n+Completing on files or directories might give nasty surprises in\n+all these cases.\n \n   * The excessive flexibility made other extensions essentially\n     impractical.  `--sparse-index` is likely impossible in non-cone\n\nbase-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\n-- \n2.51.0.352.g356bc2d8d49\n\n"},{"id":"528451","messageId":"20251010050207.GA1897715@coredump.intra.peff.net","threadId":"64272","inReplyTo":"7a955ecb1b5.1759923933.git.code@khaugsbakk.name","subject":"Re: [PATCH] doc: fix accidental literal blocks","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2025-10-10T05:02:07Z","receivedAt":"2025-10-10T05:02:10Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 08, 2025 at 01:48:46PM +0200, kristofferhaugsbakk@fastmail.com wrote:\n\n> Make sure that normal paragraphs in most user-facing docs[1] don’t\n> use literal blocks. This can easily happen if you try to maintain\n> indentation in order to continue a block; that might work in\n> e.g. Markdown variants, but not in AsciiDoc.\n> \n> The fixes are straightforward, i.e. just deindent the block and maybe\n> add line continuations. The only exception is git-sparse-checkout(1)\n> where we also replace indentation used for *intended* literal blocks\n> with `----`.\n\nI gave a quick look over the results of doc-diff before and after, and\nall of the changes look good to me.\n\n-Peff\n"},{"id":"528477","messageId":"c733f49a-5287-4d5c-9080-2ce68b25e8c4@app.fastmail.com","threadId":"64272","inReplyTo":"20251010050207.GA1897715@coredump.intra.peff.net","subject":"Re: [PATCH] doc: fix accidental literal blocks","fromName":"Kristoffer Haugsbakk","fromEmail":"code@khaugsbakk.name","sentAt":"2025-10-10T09:35:48Z","receivedAt":"2025-10-10T09:36:10Z","isPatch":true,"sender":{"key":"code@khaugsbakk.name","avatar":"https://avatars.githubusercontent.com/u/2229597?v=4"},"body":"On Fri, Oct 10, 2025, at 07:02, Jeff King wrote:\n>>[snip]\n>\n> I gave a quick look over the results of doc-diff before and after, and\n> all of the changes look good to me.\n\nThanks!\n"},{"id":"528478","messageId":"v2-619841a5663.1760088970.git.code@khaugsbakk.name","threadId":"64272","inReplyTo":"7a955ecb1b5.1759923933.git.code@khaugsbakk.name","subject":"[PATCH v2] doc: fix accidental literal blocks","fromName":"","fromEmail":"kristofferhaugsbakk@fastmail.com","sentAt":"2025-10-10T09:37:27Z","receivedAt":"2025-10-10T09:38:18Z","isPatch":true,"sender":{"key":"kristofferhaugsbakk@fastmail.com","avatar":null},"body":"From: Kristoffer Haugsbakk <code@khaugsbakk.name>\n\nMake sure that normal paragraphs in most user-facing docs[1] don’t\nuse literal blocks. This can easily happen if you try to maintain\nindentation in order to continue a block; that might work in\ne.g. Markdown variants, but not in AsciiDoc.\n\nThe fixes are straightforward, i.e. just deindent the block and maybe\nadd line continuations. The only exception is git-sparse-checkout(1)\nwhere we also replace indentation used for *intended* literal blocks\nwith `----`.\n\n† 1: These have not been considered:\n     • `Documentation/howto/`\n     • `Documentation/technical/`\n     • `Documentation/gitprotocol*`\n\nAcked-by: Jeff King <peff@peff.net>\nSigned-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n---\n\nNotes (series):\n    v2:\n    \n    • Add ack\n    \n    § Cover letter text\n    \n    I have noticed and sent patches for these things in the past because I\n    randomly spotted them, more or less.  This time though I have tried to\n    go through the docs and actively look for them.  These should be the\n    only ones if my hunting approach was sound.\n    \n    About not considering those other docs:\n    \n    In general, the *technical* documentation has worse HTML output than the\n    more user-facing docs, to the point where it looks like they might not\n    have been written with output formats/publishing in mind. So there might\n    not be a point to fixing them.\n    \n    I could have fixed one paragraph in gitprotocol-v2 but then that raises\n    the question of what about the other paragraphs? That in turn made the\n    commit message too long just for that point so I dropped it.\n\n Documentation/config/core.adoc         |  4 +-\n Documentation/git-config.adoc          | 18 +++----\n Documentation/git-rev-parse.adoc       | 14 ++---\n Documentation/git-shortlog.adoc        |  4 +-\n Documentation/git-sparse-checkout.adoc | 72 ++++++++++++++++----------\n 5 files changed, 64 insertions(+), 48 deletions(-)\n\ndiff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc\nindex 3fbe83eef16..8866ed27714 100644\n--- a/Documentation/config/core.adoc\n+++ b/Documentation/config/core.adoc\n@@ -75,8 +75,8 @@ The built-in file system monitor is currently available only on a\n limited set of supported platforms.  Currently, this includes Windows\n and MacOS.\n +\n-\tOtherwise, this variable contains the pathname of the \"fsmonitor\"\n-\thook command.\n+Otherwise, this variable contains the pathname of the \"fsmonitor\"\n+hook command.\n +\n This hook command is used to identify all files that may have changed\n since the requested date/time. This information is used to speed up\ndiff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc\nindex 511b2e26bfb..a633ab8ec3a 100644\n--- a/Documentation/git-config.adoc\n+++ b/Documentation/git-config.adoc\n@@ -117,15 +117,15 @@ OPTIONS\n \n --comment <message>::\n \tAppend a comment at the end of new or modified lines.\n-\n-\tIf _<message>_ begins with one or more whitespaces followed\n-\tby \"#\", it is used as-is.  If it begins with \"#\", a space is\n-\tprepended before it is used.  Otherwise, a string \" # \" (a\n-\tspace followed by a hash followed by a space) is prepended\n-\tto it.  And the resulting string is placed immediately after\n-\tthe value defined for the variable.  The _<message>_ must\n-\tnot contain linefeed characters (no multi-line comments are\n-\tpermitted).\n++\n+If _<message>_ begins with one or more whitespaces followed\n+by \"#\", it is used as-is.  If it begins with \"#\", a space is\n+prepended before it is used.  Otherwise, a string \" # \" (a\n+space followed by a hash followed by a space) is prepended\n+to it.  And the resulting string is placed immediately after\n+the value defined for the variable.  The _<message>_ must\n+not contain linefeed characters (no multi-line comments are\n+permitted).\n \n --all::\n \tWith `get`, return all values for a multi-valued key.\ndiff --git a/Documentation/git-rev-parse.adoc b/Documentation/git-rev-parse.adoc\nindex cc32b4b4f0f..18383e52af7 100644\n--- a/Documentation/git-rev-parse.adoc\n+++ b/Documentation/git-rev-parse.adoc\n@@ -174,13 +174,13 @@ for another option.\n \n \tAllow oids to be input from any object format that the current\n \trepository supports.\n-\n-\tSpecifying \"sha1\" translates if necessary and returns a sha1 oid.\n-\n-\tSpecifying \"sha256\" translates if necessary and returns a sha256 oid.\n-\n-\tSpecifying \"storage\" translates if necessary and returns an oid in\n-\tencoded in the storage hash algorithm.\n++\n+Specifying \"sha1\" translates if necessary and returns a sha1 oid.\n++\n+Specifying \"sha256\" translates if necessary and returns a sha256 oid.\n++\n+Specifying \"storage\" translates if necessary and returns an oid in\n+encoded in the storage hash algorithm.\n \n Options for Objects\n ~~~~~~~~~~~~~~~~~~~\ndiff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc\nindex d8ab38dcc1f..aa92800c69c 100644\n--- a/Documentation/git-shortlog.adoc\n+++ b/Documentation/git-shortlog.adoc\n@@ -44,8 +44,8 @@ OPTIONS\n \tdescribe each commit.  '<format>' can be any string accepted\n \tby the `--format` option of 'git log', such as '* [%h] %s'.\n \t(See the \"PRETTY FORMATS\" section of linkgit:git-log[1].)\n-\n-\tEach pretty-printed commit will be rewrapped before it is shown.\n++\n+Each pretty-printed commit will be rewrapped before it is shown.\n \n --date=<format>::\n \tShow dates formatted according to the given date string. (See\ndiff --git a/Documentation/git-sparse-checkout.adoc b/Documentation/git-sparse-checkout.adoc\nindex 529a8edd9c1..b5fe5da0416 100644\n--- a/Documentation/git-sparse-checkout.adoc\n+++ b/Documentation/git-sparse-checkout.adoc\n@@ -264,34 +264,50 @@ patterns in non-cone mode has a number of shortcomings:\n     inconsistent.\n \n   * It has edge cases where the \"right\" behavior is unclear.  Two examples:\n-\n-    First, two users are in a subdirectory, and the first runs\n-       git sparse-checkout set '/toplevel-dir/*.c'\n-    while the second runs\n-       git sparse-checkout set relative-dir\n-    Should those arguments be transliterated into\n-       current/subdirectory/toplevel-dir/*.c\n-    and\n-       current/subdirectory/relative-dir\n-    before inserting into the sparse-checkout file?  The user who typed\n-    the first command is probably aware that arguments to set/add are\n-    supposed to be patterns in non-cone mode, and probably would not be\n-    happy with such a transliteration.  However, many gitignore-style\n-    patterns are just paths, which might be what the user who typed the\n-    second command was thinking, and they'd be upset if their argument\n-    wasn't transliterated.\n-\n-    Second, what should bash-completion complete on for set/add commands\n-    for non-cone users?  If it suggests paths, is it exacerbating the\n-    problem above?  Also, if it suggests paths, what if the user has a\n-    file or directory that begins with either a '!' or '#' or has a '*',\n-    '\\', '?', '[', or ']' in its name?  And if it suggests paths, will\n-    it complete \"/pro\" to \"/proc\" (in the root filesystem) rather than to\n-    \"/progress.txt\" in the current directory?  (Note that users are\n-    likely to want to start paths with a leading '/' in non-cone mode,\n-    for the same reason that .gitignore files often have one.)\n-    Completing on files or directories might give nasty surprises in\n-    all these cases.\n++\n+First, two users are in a subdirectory, and the first runs\n++\n+----\n+git sparse-checkout set '/toplevel-dir/*.c'\n+----\n++\n+while the second runs\n++\n+----\n+git sparse-checkout set relative-dir\n+----\n++\n+Should those arguments be transliterated into\n++\n+----\n+current/subdirectory/toplevel-dir/*.c\n+----\n++\n+and\n++\n+----\n+current/subdirectory/relative-dir\n+----\n++\n+before inserting into the sparse-checkout file?  The user who typed\n+the first command is probably aware that arguments to set/add are\n+supposed to be patterns in non-cone mode, and probably would not be\n+happy with such a transliteration.  However, many gitignore-style\n+patterns are just paths, which might be what the user who typed the\n+second command was thinking, and they'd be upset if their argument\n+wasn't transliterated.\n++\n+Second, what should bash-completion complete on for set/add commands\n+for non-cone users?  If it suggests paths, is it exacerbating the\n+problem above?  Also, if it suggests paths, what if the user has a\n+file or directory that begins with either a '!' or '#' or has a '*',\n+'\\', '?', '[', or ']' in its name?  And if it suggests paths, will\n+it complete \"/pro\" to \"/proc\" (in the root filesystem) rather than to\n+\"/progress.txt\" in the current directory?  (Note that users are\n+likely to want to start paths with a leading '/' in non-cone mode,\n+for the same reason that .gitignore files often have one.)\n+Completing on files or directories might give nasty surprises in\n+all these cases.\n \n   * The excessive flexibility made other extensions essentially\n     impractical.  `--sparse-index` is likely impossible in non-cone\n\nInterdiff against v1:\n\nRange-diff against v1:\n1:  7a955ecb1b5 ! 1:  619841a5663 doc: fix accidental literal blocks\n    @@ Commit message\n              • `Documentation/technical/`\n              • `Documentation/gitprotocol*`\n     \n    +    Acked-by: Jeff King <peff@peff.net>\n         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>\n     \n     \n      ## Notes (series) ##\n    +    v2:\n    +\n    +    • Add ack\n    +\n    +    § Cover letter text\n    +\n         I have noticed and sent patches for these things in the past because I\n         randomly spotted them, more or less.  This time though I have tried to\n         go through the docs and actively look for them.  These should be the\n\nbase-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0\n-- \n2.51.0.352.g356bc2d8d49\n\n"}]}