Subject: [PATCH] fixup! vimdiff: add tool documentation

From: Philippe Blain <[email-masked]>
Date: Sun, 27 Mar 2022 14:50:44 -0400

- Use Asciidoc's syntax for "list continuation" and "open block" [1]
- Remove '-->' which mixes up the parser

[1] https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation

Signed-off-by: Philippe Blain <[email-masked]>
---
 Documentation/mergetools/vimdiff.txt | 81 +++++++++++++++-------------
 1 file changed, 44 insertions(+), 37 deletions(-)

diff --git a/Documentation/mergetools/vimdiff.txt b/Documentation/mergetools/vimdiff.txt
index 296bc76e98..1017527e7d 100644
--- a/Documentation/mergetools/vimdiff.txt
+++ b/Documentation/mergetools/vimdiff.txt
@@ -42,18 +42,20 @@ it):
 
 Let's see some examples to understand how it works:
 
-  * layout = "(LOCAL,BASE,REMOTE)/MERGED"
+* `layout = "(LOCAL,BASE,REMOTE)/MERGED"`
++
+--
+This is exactly the same as the default layout we have already seen.
 
-    This is exactly the same as the default layout we have already seen.
-
-    Note that "/" has precedence over "," and thus the parenthesis are not
-    needed in this case. The next layout definition is equivalent:
+Note that "/" has precedence over "," and thus the parenthesis are not
+needed in this case. The next layout definition is equivalent:
 
         layout = "LOCAL,BASE,REMOTE / MERGED"
-
-  * layout = "LOCAL,MERGED,REMOTE"
-
-    If, for some reason, we are not interested in the "BASE" buffer.
+--
+* `layout = "LOCAL,MERGED,REMOTE"`
++
+--
+If, for some reason, we are not interested in the "BASE" buffer.
 
            ------------------------------------------
            |             |           |              |
@@ -62,12 +64,13 @@ Let's see some examples to understand how it works:
            |             |           |              |
            |             |           |              |
            ------------------------------------------
-
-  * layout = "MERGED"
-
-    Only the "MERGED" buffer will be shown. Note, however, that all the other
-    ones are still loaded in vim, and you can access them with the "buffers"
-    command. 
+--
+* `layout = "MERGED"`
++
+--
+Only the "MERGED" buffer will be shown. Note, however, that all the other
+ones are still loaded in vim, and you can access them with the "buffers"
+command.
 
            ------------------------------------------
            |                                        |
@@ -76,12 +79,13 @@ Let's see some examples to understand how it works:
            |                                        |
            |                                        |
            ------------------------------------------
-
-  * layout = "@LOCAL,REMOTE"
-
-    When "MERGED" is not present in the layout, you must "mark" one of the
-    buffers with an asterisk. That will become the buffer you need to edit and
-    save after resolving the conflicts.
+--
+* `layout = "@LOCAL,REMOTE"`
++
+--
+When "MERGED" is not present in the layout, you must "mark" one of the
+buffers with an asterisk. That will become the buffer you need to edit and
+save after resolving the conflicts.
 
            ------------------------------------------
            |                   |                    |
@@ -92,12 +96,13 @@ Let's see some examples to understand how it works:
            |                   |                    |
            |                   |                    |
            ------------------------------------------
-
-  * layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE"
-
-    Three tabs will open: the first one is a copy of the default layout, while
-    the other two only show the differences between "BASE" and "LOCAL" and
-    "BASE" and "REMOTE" respectively.
+--
+* `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE"`
++
+--
+Three tabs will open: the first one is a copy of the default layout, while
+the other two only show the differences between "BASE" and "LOCAL" and
+"BASE" and "REMOTE" respectively.
  
            ------------------------------------------
            | <TAB #1> |  TAB #2  |  TAB #3  |       |
@@ -134,11 +139,12 @@ Let's see some examples to understand how it works:
            |                   |                    |
            |                   |                    |
            ------------------------------------------
-
-  * layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE + (LOCAL/BASE/REMOTE),MERGED"
-
-    Same as the previous example, but adds a fourth tab with the same
-    information as the first tab, with a different layout.
+--
+* `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE + (LOCAL/BASE/REMOTE),MERGED"`
++
+--
+Same as the previous example, but adds a fourth tab with the same
+information as the first tab, with a different layout.
  
            ---------------------------------------------
            |  TAB #1  |  TAB #2  |  TAB #3  | <TAB #4> |
@@ -150,8 +156,9 @@ Let's see some examples to understand how it works:
            |       REMOTE        |                     |
            ---------------------------------------------
 
-    Note how in the third tab definition we need to use parenthesis to make ","
-    have precedence over "/".
+Note how in the third tab definition we need to use parenthesis to make ","
+have precedence over "/".
+--
 
 Variants
 ^^^^^^^^
@@ -173,9 +180,9 @@ In other words, using `--tool=[g,n,]vimdiffx` is the same as using
 `--tool=[g,n,]vimdiff` and setting configuration variable
 `mergetool.[g,n,]vimdiff.layout` to... 
 
-  * x=1 --> "@LOCAL, REMOTE"
-  * x=2 --> "LOCAL, MERGED, REMOTE"
-  * x=3 --> "MERGED"
+  * `x=1`: `"@LOCAL, REMOTE"`
+  * `x=2`: `"LOCAL, MERGED, REMOTE"`
+  * `x=3`: `"MERGED"`
 
 Example: using `--tool=gvimdiff2` will open `gvim` with three columns (LOCAL,
 MERGED and REMOTE).
-- 
2.29.2