[PATCH] doc: fix accidental literal blocks

[PATCH] doc: fix accidental literal blocks

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Make sure that normal paragraphs in most user-facing docs[1] don’t
use literal blocks. This can easily happen if you try to maintain
indentation in order to continue a block; that might work in
e.g. Markdown variants, but not in AsciiDoc.

The fixes are straightforward, i.e. just deindent the block and maybe
add line continuations. The only exception is git-sparse-checkout(1)
where we also replace indentation used for *intended* literal blocks
with `----`.

† 1: These have not been considered:
     • `Documentation/howto/`
     • `Documentation/technical/`
     • `Documentation/gitprotocol*`

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    I have noticed and sent patches for these things in the past because I
    randomly spotted them, more or less.  This time though I have tried to
    go through the docs and actively look for them.  These should be the
    only ones if my hunting approach was sound.
    
    About not considering those other docs:
    
    In general, the *technical* documentation has worse HTML output than the
    more user-facing docs, to the point where it looks like they might not
    have been written with output formats/publishing in mind. So there might
    not be a point to fixing them.
    
    I could have fixed one paragraph in gitprotocol-v2 but then that raises
    the question of what about the other paragraphs? That in turn made the
    commit message too long just for that point so I dropped it.

 Documentation/config/core.adoc         |  4 +-
 Documentation/git-config.adoc          | 18 +++----
 Documentation/git-rev-parse.adoc       | 14 ++---
 Documentation/git-shortlog.adoc        |  4 +-
 Documentation/git-sparse-checkout.adoc | 72 ++++++++++++++++----------
 5 files changed, 64 insertions(+), 48 deletions(-)

diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc
index 3fbe83eef16..8866ed27714 100644
--- a/Documentation/config/core.adoc
+++ b/Documentation/config/core.adoc
@@ -75,8 +75,8 @@ The built-in file system monitor is currently available only on a
 limited set of supported platforms.  Currently, this includes Windows
 and MacOS.
 +
-	Otherwise, this variable contains the pathname of the "fsmonitor"
-	hook command.
+Otherwise, this variable contains the pathname of the "fsmonitor"
+hook command.
 +
 This hook command is used to identify all files that may have changed
 since the requested date/time. This information is used to speed up
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 511b2e26bfb..a633ab8ec3a 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -117,15 +117,15 @@ OPTIONS
 
 --comment <message>::
 	Append a comment at the end of new or modified lines.
-
-	If _<message>_ begins with one or more whitespaces followed
-	by "#", it is used as-is.  If it begins with "#", a space is
-	prepended before it is used.  Otherwise, a string " # " (a
-	space followed by a hash followed by a space) is prepended
-	to it.  And the resulting string is placed immediately after
-	the value defined for the variable.  The _<message>_ must
-	not contain linefeed characters (no multi-line comments are
-	permitted).
++
+If _<message>_ begins with one or more whitespaces followed
+by "#", it is used as-is.  If it begins with "#", a space is
+prepended before it is used.  Otherwise, a string " # " (a
+space followed by a hash followed by a space) is prepended
+to it.  And the resulting string is placed immediately after
+the value defined for the variable.  The _<message>_ must
+not contain linefeed characters (no multi-line comments are
+permitted).
 
 --all::
 	With `get`, return all values for a multi-valued key.
diff --git a/Documentation/git-rev-parse.adoc b/Documentation/git-rev-parse.adoc
index cc32b4b4f0f..18383e52af7 100644
--- a/Documentation/git-rev-parse.adoc
+++ b/Documentation/git-rev-parse.adoc
@@ -174,13 +174,13 @@ for another option.
 
 	Allow oids to be input from any object format that the current
 	repository supports.
-
-	Specifying "sha1" translates if necessary and returns a sha1 oid.
-
-	Specifying "sha256" translates if necessary and returns a sha256 oid.
-
-	Specifying "storage" translates if necessary and returns an oid in
-	encoded in the storage hash algorithm.
++
+Specifying "sha1" translates if necessary and returns a sha1 oid.
++
+Specifying "sha256" translates if necessary and returns a sha256 oid.
++
+Specifying "storage" translates if necessary and returns an oid in
+encoded in the storage hash algorithm.
 
 Options for Objects
 ~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc
index d8ab38dcc1f..aa92800c69c 100644
--- a/Documentation/git-shortlog.adoc
+++ b/Documentation/git-shortlog.adoc
@@ -44,8 +44,8 @@ OPTIONS
 	describe each commit.  '<format>' can be any string accepted
 	by the `--format` option of 'git log', such as '* [%h] %s'.
 	(See the "PRETTY FORMATS" section of linkgit:git-log[1].)
-
-	Each pretty-printed commit will be rewrapped before it is shown.
++
+Each pretty-printed commit will be rewrapped before it is shown.
 
 --date=<format>::
 	Show dates formatted according to the given date string. (See
diff --git a/Documentation/git-sparse-checkout.adoc b/Documentation/git-sparse-checkout.adoc
index 529a8edd9c1..b5fe5da0416 100644
--- a/Documentation/git-sparse-checkout.adoc
+++ b/Documentation/git-sparse-checkout.adoc
@@ -264,34 +264,50 @@ patterns in non-cone mode has a number of shortcomings:
     inconsistent.
 
   * It has edge cases where the "right" behavior is unclear.  Two examples:
-
-    First, two users are in a subdirectory, and the first runs
-       git sparse-checkout set '/toplevel-dir/*.c'
-    while the second runs
-       git sparse-checkout set relative-dir
-    Should those arguments be transliterated into
-       current/subdirectory/toplevel-dir/*.c
-    and
-       current/subdirectory/relative-dir
-    before inserting into the sparse-checkout file?  The user who typed
-    the first command is probably aware that arguments to set/add are
-    supposed to be patterns in non-cone mode, and probably would not be
-    happy with such a transliteration.  However, many gitignore-style
-    patterns are just paths, which might be what the user who typed the
-    second command was thinking, and they'd be upset if their argument
-    wasn't transliterated.
-
-    Second, what should bash-completion complete on for set/add commands
-    for non-cone users?  If it suggests paths, is it exacerbating the
-    problem above?  Also, if it suggests paths, what if the user has a
-    file or directory that begins with either a '!' or '#' or has a '*',
-    '\', '?', '[', or ']' in its name?  And if it suggests paths, will
-    it complete "/pro" to "/proc" (in the root filesystem) rather than to
-    "/progress.txt" in the current directory?  (Note that users are
-    likely to want to start paths with a leading '/' in non-cone mode,
-    for the same reason that .gitignore files often have one.)
-    Completing on files or directories might give nasty surprises in
-    all these cases.
++
+First, two users are in a subdirectory, and the first runs
++
+----
+git sparse-checkout set '/toplevel-dir/*.c'
+----
++
+while the second runs
++
+----
+git sparse-checkout set relative-dir
+----
++
+Should those arguments be transliterated into
++
+----
+current/subdirectory/toplevel-dir/*.c
+----
++
+and
++
+----
+current/subdirectory/relative-dir
+----
++
+before inserting into the sparse-checkout file?  The user who typed
+the first command is probably aware that arguments to set/add are
+supposed to be patterns in non-cone mode, and probably would not be
+happy with such a transliteration.  However, many gitignore-style
+patterns are just paths, which might be what the user who typed the
+second command was thinking, and they'd be upset if their argument
+wasn't transliterated.
++
+Second, what should bash-completion complete on for set/add commands
+for non-cone users?  If it suggests paths, is it exacerbating the
+problem above?  Also, if it suggests paths, what if the user has a
+file or directory that begins with either a '!' or '#' or has a '*',
+'\', '?', '[', or ']' in its name?  And if it suggests paths, will
+it complete "/pro" to "/proc" (in the root filesystem) rather than to
+"/progress.txt" in the current directory?  (Note that users are
+likely to want to start paths with a leading '/' in non-cone mode,
+for the same reason that .gitignore files often have one.)
+Completing on files or directories might give nasty surprises in
+all these cases.
 
   * The excessive flexibility made other extensions essentially
     impractical.  `--sparse-index` is likely impossible in non-cone

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
-- 
2.51.0.352.g356bc2d8d49

Re: [PATCH] doc: fix accidental literal blocks

[Jeff King]

On Wed, Oct 08, 2025 at 01:48:46PM +0200, kristofferhaugsbakk@fastmail.com wrote:

> Make sure that normal paragraphs in most user-facing docs[1] don’t
> use literal blocks. This can easily happen if you try to maintain
> indentation in order to continue a block; that might work in
> e.g. Markdown variants, but not in AsciiDoc.
> 
> The fixes are straightforward, i.e. just deindent the block and maybe
> add line continuations. The only exception is git-sparse-checkout(1)
> where we also replace indentation used for *intended* literal blocks
> with `----`.

I gave a quick look over the results of doc-diff before and after, and
all of the changes look good to me.

-Peff

Re: [PATCH] doc: fix accidental literal blocks

[Kristoffer Haugsbakk]

On Fri, Oct 10, 2025, at 07:02, Jeff King wrote:
>>[snip]
>
> I gave a quick look over the results of doc-diff before and after, and
> all of the changes look good to me.

Thanks!

[PATCH v2] doc: fix accidental literal blocks

[kristofferhaugsbakk]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Make sure that normal paragraphs in most user-facing docs[1] don’t
use literal blocks. This can easily happen if you try to maintain
indentation in order to continue a block; that might work in
e.g. Markdown variants, but not in AsciiDoc.

The fixes are straightforward, i.e. just deindent the block and maybe
add line continuations. The only exception is git-sparse-checkout(1)
where we also replace indentation used for *intended* literal blocks
with `----`.

† 1: These have not been considered:
     • `Documentation/howto/`
     • `Documentation/technical/`
     • `Documentation/gitprotocol*`

Acked-by: Jeff King <peff@peff.net>
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---

Notes (series):
    v2:
    
    • Add ack
    
    § Cover letter text
    
    I have noticed and sent patches for these things in the past because I
    randomly spotted them, more or less.  This time though I have tried to
    go through the docs and actively look for them.  These should be the
    only ones if my hunting approach was sound.
    
    About not considering those other docs:
    
    In general, the *technical* documentation has worse HTML output than the
    more user-facing docs, to the point where it looks like they might not
    have been written with output formats/publishing in mind. So there might
    not be a point to fixing them.
    
    I could have fixed one paragraph in gitprotocol-v2 but then that raises
    the question of what about the other paragraphs? That in turn made the
    commit message too long just for that point so I dropped it.

 Documentation/config/core.adoc         |  4 +-
 Documentation/git-config.adoc          | 18 +++----
 Documentation/git-rev-parse.adoc       | 14 ++---
 Documentation/git-shortlog.adoc        |  4 +-
 Documentation/git-sparse-checkout.adoc | 72 ++++++++++++++++----------
 5 files changed, 64 insertions(+), 48 deletions(-)

diff --git a/Documentation/config/core.adoc b/Documentation/config/core.adoc
index 3fbe83eef16..8866ed27714 100644
--- a/Documentation/config/core.adoc
+++ b/Documentation/config/core.adoc
@@ -75,8 +75,8 @@ The built-in file system monitor is currently available only on a
 limited set of supported platforms.  Currently, this includes Windows
 and MacOS.
 +
-	Otherwise, this variable contains the pathname of the "fsmonitor"
-	hook command.
+Otherwise, this variable contains the pathname of the "fsmonitor"
+hook command.
 +
 This hook command is used to identify all files that may have changed
 since the requested date/time. This information is used to speed up
diff --git a/Documentation/git-config.adoc b/Documentation/git-config.adoc
index 511b2e26bfb..a633ab8ec3a 100644
--- a/Documentation/git-config.adoc
+++ b/Documentation/git-config.adoc
@@ -117,15 +117,15 @@ OPTIONS
 
 --comment <message>::
 	Append a comment at the end of new or modified lines.
-
-	If _<message>_ begins with one or more whitespaces followed
-	by "#", it is used as-is.  If it begins with "#", a space is
-	prepended before it is used.  Otherwise, a string " # " (a
-	space followed by a hash followed by a space) is prepended
-	to it.  And the resulting string is placed immediately after
-	the value defined for the variable.  The _<message>_ must
-	not contain linefeed characters (no multi-line comments are
-	permitted).
++
+If _<message>_ begins with one or more whitespaces followed
+by "#", it is used as-is.  If it begins with "#", a space is
+prepended before it is used.  Otherwise, a string " # " (a
+space followed by a hash followed by a space) is prepended
+to it.  And the resulting string is placed immediately after
+the value defined for the variable.  The _<message>_ must
+not contain linefeed characters (no multi-line comments are
+permitted).
 
 --all::
 	With `get`, return all values for a multi-valued key.
diff --git a/Documentation/git-rev-parse.adoc b/Documentation/git-rev-parse.adoc
index cc32b4b4f0f..18383e52af7 100644
--- a/Documentation/git-rev-parse.adoc
+++ b/Documentation/git-rev-parse.adoc
@@ -174,13 +174,13 @@ for another option.
 
 	Allow oids to be input from any object format that the current
 	repository supports.
-
-	Specifying "sha1" translates if necessary and returns a sha1 oid.
-
-	Specifying "sha256" translates if necessary and returns a sha256 oid.
-
-	Specifying "storage" translates if necessary and returns an oid in
-	encoded in the storage hash algorithm.
++
+Specifying "sha1" translates if necessary and returns a sha1 oid.
++
+Specifying "sha256" translates if necessary and returns a sha256 oid.
++
+Specifying "storage" translates if necessary and returns an oid in
+encoded in the storage hash algorithm.
 
 Options for Objects
 ~~~~~~~~~~~~~~~~~~~
diff --git a/Documentation/git-shortlog.adoc b/Documentation/git-shortlog.adoc
index d8ab38dcc1f..aa92800c69c 100644
--- a/Documentation/git-shortlog.adoc
+++ b/Documentation/git-shortlog.adoc
@@ -44,8 +44,8 @@ OPTIONS
 	describe each commit.  '<format>' can be any string accepted
 	by the `--format` option of 'git log', such as '* [%h] %s'.
 	(See the "PRETTY FORMATS" section of linkgit:git-log[1].)
-
-	Each pretty-printed commit will be rewrapped before it is shown.
++
+Each pretty-printed commit will be rewrapped before it is shown.
 
 --date=<format>::
 	Show dates formatted according to the given date string. (See
diff --git a/Documentation/git-sparse-checkout.adoc b/Documentation/git-sparse-checkout.adoc
index 529a8edd9c1..b5fe5da0416 100644
--- a/Documentation/git-sparse-checkout.adoc
+++ b/Documentation/git-sparse-checkout.adoc
@@ -264,34 +264,50 @@ patterns in non-cone mode has a number of shortcomings:
     inconsistent.
 
   * It has edge cases where the "right" behavior is unclear.  Two examples:
-
-    First, two users are in a subdirectory, and the first runs
-       git sparse-checkout set '/toplevel-dir/*.c'
-    while the second runs
-       git sparse-checkout set relative-dir
-    Should those arguments be transliterated into
-       current/subdirectory/toplevel-dir/*.c
-    and
-       current/subdirectory/relative-dir
-    before inserting into the sparse-checkout file?  The user who typed
-    the first command is probably aware that arguments to set/add are
-    supposed to be patterns in non-cone mode, and probably would not be
-    happy with such a transliteration.  However, many gitignore-style
-    patterns are just paths, which might be what the user who typed the
-    second command was thinking, and they'd be upset if their argument
-    wasn't transliterated.
-
-    Second, what should bash-completion complete on for set/add commands
-    for non-cone users?  If it suggests paths, is it exacerbating the
-    problem above?  Also, if it suggests paths, what if the user has a
-    file or directory that begins with either a '!' or '#' or has a '*',
-    '\', '?', '[', or ']' in its name?  And if it suggests paths, will
-    it complete "/pro" to "/proc" (in the root filesystem) rather than to
-    "/progress.txt" in the current directory?  (Note that users are
-    likely to want to start paths with a leading '/' in non-cone mode,
-    for the same reason that .gitignore files often have one.)
-    Completing on files or directories might give nasty surprises in
-    all these cases.
++
+First, two users are in a subdirectory, and the first runs
++
+----
+git sparse-checkout set '/toplevel-dir/*.c'
+----
++
+while the second runs
++
+----
+git sparse-checkout set relative-dir
+----
++
+Should those arguments be transliterated into
++
+----
+current/subdirectory/toplevel-dir/*.c
+----
++
+and
++
+----
+current/subdirectory/relative-dir
+----
++
+before inserting into the sparse-checkout file?  The user who typed
+the first command is probably aware that arguments to set/add are
+supposed to be patterns in non-cone mode, and probably would not be
+happy with such a transliteration.  However, many gitignore-style
+patterns are just paths, which might be what the user who typed the
+second command was thinking, and they'd be upset if their argument
+wasn't transliterated.
++
+Second, what should bash-completion complete on for set/add commands
+for non-cone users?  If it suggests paths, is it exacerbating the
+problem above?  Also, if it suggests paths, what if the user has a
+file or directory that begins with either a '!' or '#' or has a '*',
+'\', '?', '[', or ']' in its name?  And if it suggests paths, will
+it complete "/pro" to "/proc" (in the root filesystem) rather than to
+"/progress.txt" in the current directory?  (Note that users are
+likely to want to start paths with a leading '/' in non-cone mode,
+for the same reason that .gitignore files often have one.)
+Completing on files or directories might give nasty surprises in
+all these cases.
 
   * The excessive flexibility made other extensions essentially
     impractical.  `--sparse-index` is likely impossible in non-cone

Interdiff against v1:

Range-diff against v1:
1:  7a955ecb1b5 ! 1:  619841a5663 doc: fix accidental literal blocks
    @@ Commit message
              • `Documentation/technical/`
              • `Documentation/gitprotocol*`
     
    +    Acked-by: Jeff King <peff@peff.net>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    +    v2:
    +
    +    • Add ack
    +
    +    § Cover letter text
    +
         I have noticed and sent patches for these things in the past because I
         randomly spotted them, more or less.  This time though I have tried to
         go through the docs and actively look for them.  These should be the

base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
-- 
2.51.0.352.g356bc2d8d49