diff mbox series

fixup! vimdiff: add tool documentation

Message ID 20220329125400.63337-1-levraiphilippeblain@gmail.com (mailing list archive)
State New, archived
Headers show
Series fixup! vimdiff: add tool documentation | expand

Commit Message

Philippe Blain March 29, 2022, 12:54 p.m. UTC 
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---

Hi Junio, Fernando,

I think the canonical Asciidoc way would be to use a listing block
(start and end the block with '----', and not indenting the lines
at all, as is done in a few places in the docs), but in this case
the parser gets confused about the several dashes in the content of
the block. So we can use a "literal block" instead [1].

[1] https://docs.asciidoctor.org/asciidoc/latest/verbatim/literal-blocks/

 Documentation/mergetools/vimdiff.txt | 174 ++++++++++++++-------------
 1 file changed, 90 insertions(+), 84 deletions(-)

Comments

Junio C Hamano March 29, 2022, 4:03 p.m. UTC | #1 
Philippe Blain <levraiphilippeblain@gmail.com> writes:

> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
>
> Hi Junio, Fernando,
>
> I think the canonical Asciidoc way would be to use a listing block
> (start and end the block with '----', and not indenting the lines
> at all, as is done in a few places in the docs), but in this case
> the parser gets confused about the several dashes in the content of
> the block. So we can use a "literal block" instead [1].
>
> [1] https://docs.asciidoctor.org/asciidoc/latest/verbatim/literal-blocks/

Thanks, will queue on top (without squashing) for now, expecting
that Fernando may want to send in another round of updates (and if
it turns out that this is the only fix-up we need, then we can just
squash it in later before merging the topic to 'next').
diff mbox series

Patch

diff --git a/Documentation/mergetools/vimdiff.txt b/Documentation/mergetools/vimdiff.txt
index f63fc48c29..1cc9c133f9 100644
--- a/Documentation/mergetools/vimdiff.txt
+++ b/Documentation/mergetools/vimdiff.txt
@@ -3,17 +3,17 @@  Description
 
 When specifying `--tool=vimdiff` in `git mergetool` Git will open Vim with a 4
 windows layout distributed in the following way:
-
-    ------------------------------------------
-    |             |           |              |
-    |   LOCAL     |   BASE    |   REMOTE     |
-    |             |           |              |
-    ------------------------------------------
-    |                                        |
-    |                MERGED                  |
-    |                                        |
-    ------------------------------------------
-
+....
+------------------------------------------
+|             |           |              |
+|   LOCAL     |   BASE    |   REMOTE     |
+|             |           |              |
+------------------------------------------
+|                                        |
+|                MERGED                  |
+|                                        |
+------------------------------------------
+....
 `LOCAL`, `BASE` and `REMOTE` are read-only buffers showing the contents of the
 conflicting file in specific commits ("commit you are merging into", "common
 ancestor commit" and "commit you are merging from" respectively)
@@ -56,14 +56,15 @@  needed in this case. The next layout definition is equivalent:
 +
 --
 If, for some reason, we are not interested in the `BASE` buffer.
-
-           ------------------------------------------
-           |             |           |              |
-           |             |           |              |
-           |   LOCAL     |   MERGED  |   REMOTE     |
-           |             |           |              |
-           |             |           |              |
-           ------------------------------------------
+....
+------------------------------------------
+|             |           |              |
+|             |           |              |
+|   LOCAL     |   MERGED  |   REMOTE     |
+|             |           |              |
+|             |           |              |
+------------------------------------------
+....
 --
 * `layout = "MERGED"`
 +
@@ -71,14 +72,15 @@  If, for some reason, we are not interested in the `BASE` buffer.
 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.
-
-           ------------------------------------------
-           |                                        |
-           |                                        |
-           |                 MERGED                 |
-           |                                        |
-           |                                        |
-           ------------------------------------------
+....
+------------------------------------------
+|                                        |
+|                                        |
+|                 MERGED                 |
+|                                        |
+|                                        |
+------------------------------------------
+....
 --
 * `layout = "@LOCAL,REMOTE"`
 +
@@ -86,16 +88,17 @@  command.
 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.
-
-           ------------------------------------------
-           |                   |                    |
-           |                   |                    |
-           |                   |                    |
-           |     LOCAL         |    REMOTE          |
-           |                   |                    |
-           |                   |                    |
-           |                   |                    |
-           ------------------------------------------
+....
+------------------------------------------
+|                   |                    |
+|                   |                    |
+|                   |                    |
+|     LOCAL         |    REMOTE          |
+|                   |                    |
+|                   |                    |
+|                   |                    |
+------------------------------------------
+....
 --
 * `layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE"`
 +
@@ -103,59 +106,62 @@  save after resolving the conflicts.
 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  |       |
-           ------------------------------------------
-           |             |           |              |
-           |   LOCAL     |   BASE    |   REMOTE     |
-           |             |           |              |
-           ------------------------------------------
-           |                                        |
-           |                MERGED                  |
-           |                                        |
-           ------------------------------------------
-
-           ------------------------------------------
-           |  TAB #1  | <TAB #2> |  TAB #3  |       |
-           ------------------------------------------
-           |                   |                    |
-           |                   |                    |
-           |                   |                    |
-           |     BASE          |    LOCAL           |
-           |                   |                    |
-           |                   |                    |
-           |                   |                    |
-           ------------------------------------------
-
-           ------------------------------------------
-           |  TAB #1  |  TAB #2  | <TAB #3> |       |
-           ------------------------------------------
-           |                   |                    |
-           |                   |                    |
-           |                   |                    |
-           |     BASE          |    REMOTE          |
-           |                   |                    |
-           |                   |                    |
-           |                   |                    |
-           ------------------------------------------
+....
+------------------------------------------
+| <TAB #1> |  TAB #2  |  TAB #3  |       |
+------------------------------------------
+|             |           |              |
+|   LOCAL     |   BASE    |   REMOTE     |
+|             |           |              |
+------------------------------------------
+|                                        |
+|                MERGED                  |
+|                                        |
+------------------------------------------
+....
+....
+------------------------------------------
+|  TAB #1  | <TAB #2> |  TAB #3  |       |
+------------------------------------------
+|                   |                    |
+|                   |                    |
+|                   |                    |
+|     BASE          |    LOCAL           |
+|                   |                    |
+|                   |                    |
+|                   |                    |
+------------------------------------------
+....
+....
+------------------------------------------
+|  TAB #1  |  TAB #2  | <TAB #3> |       |
+------------------------------------------
+|                   |                    |
+|                   |                    |
+|                   |                    |
+|     BASE          |    REMOTE          |
+|                   |                    |
+|                   |                    |
+|                   |                    |
+------------------------------------------
+....
 --
 * `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> |
-           ---------------------------------------------
-           |       LOCAL         |                     |
-           |---------------------|                     |
-           |       BASE          |        MERGED       |
-           |---------------------|                     |
-           |       REMOTE        |                     |
-           ---------------------------------------------
-
+....
+---------------------------------------------
+|  TAB #1  |  TAB #2  |  TAB #3  | <TAB #4> |
+---------------------------------------------
+|       LOCAL         |                     |
+|---------------------|                     |
+|       BASE          |        MERGED       |
+|---------------------|                     |
+|       REMOTE        |                     |
+---------------------------------------------
+....
 Note how in the third tab definition we need to use parenthesis to make `,`
 have precedence over `/`.
 --