fix(tutor): Tutor steps don't work on Windows #25251

Problem:
Some steps in :Tutor don't work on Windows.

Solution:
Add support for `{unix:...,win:...}` format and transform the Tutor contents
depending on the platform.
Fix https://github.com/neovim/neovim/issues/24166

3 files changed, 113 insertions, 9 deletions

diff --git a/runtime/autoload/tutor.vim b/runtime/autoload/tutor.vim
index 80c09488d5..701be28ccc 100644
--- a/runtime/autoload/tutor.vim
+++ b/runtime/autoload/tutor.vim
@@ -220,6 +220,7 @@ function! tutor#TutorCmd(tutor_name)
 
     call tutor#SetupVim()
     exe "edit ".l:to_open
+    call tutor#ApplyTransform()
 endfunction
 
 function! tutor#TutorCmdComplete(lead,line,pos)
@@ -227,3 +228,12 @@ function! tutor#TutorCmdComplete(lead,line,pos)
     let l:names = uniq(sort(map(l:tutors, 'fnamemodify(v:val, ":t:r")'), 's:Sort'))
     return join(l:names, "\n")
 endfunction
+
+function! tutor#ApplyTransform()
+    if has('win32')        
+        sil! %s/{unix:(\(.\{-}\)),win:(\(.\{-}\))}/\2/g
+    else
+        sil! %s/{unix:(\(.\{-}\)),win:(\(.\{-}\))}/\1/g
+    endif
+    normal! gg0
+endfunction
diff --git a/runtime/tutor/en/vim-01-beginner.tutor b/runtime/tutor/en/vim-01-beginner.tutor
index 71b196d189..2824f7ae83 100644
--- a/runtime/tutor/en/vim-01-beginner.tutor
+++ b/runtime/tutor/en/vim-01-beginner.tutor
@@ -629,7 +629,7 @@ NOTE: All `:`{vim} commands are executed when you press `<Enter>`{normal}.
 
 ** To save the changes made to the text, type `:w`{vim} FILENAME. **
 
- 1. Type `:!ls`{vim} to get a listing of your directory.
+ 1. Type `:!{unix:(ls),win:(dir)}`{vim} to get a listing of your directory.
     You already know you must hit `<Enter>`{normal} after this.
 
  2. Choose a filename that does not exist yet, such as TEST.
@@ -641,14 +641,14 @@ NOTE: All `:`{vim} commands are executed when you press `<Enter>`{normal}.
    (where TEST is the filename you chose.)
 
  4. This saves the current file under the name TEST.
-    To verify this, type `:!ls`{vim} again to see your directory.
+    To verify this, type `:!{unix:(ls),win:(dir)}`{vim} again to see your directory.
 
 NOTE: If you were to exit Neovim and start it again with `nvim TEST`, the file
       would be an exact copy of the tutorial when you saved it.
 
  5. Now remove the file by typing:
 ~~~ cmd
-        :!rm TEST
+        :!{unix:(rm),win:(del)} TEST
 ~~~
 # Lesson 5.3: SELECTING TEXT TO WRITE
 
@@ -675,7 +675,7 @@ NOTE: If you were to exit Neovim and start it again with `nvim TEST`, the file
 
     before you press `<Enter>`{normal}.
 
- 5. Neovim will write the selected lines to the file TEST. Use `:!ls`{vim} to see it.
+ 5. Neovim will write the selected lines to the file TEST. Use `:!{unix:(ls),win:(dir)}`{vim} to see it.
     Do not remove it yet! We will use it in the next lesson.
 
 NOTE: Pressing [v](v) starts [Visual selection](visual-mode). You can move the cursor around to
@@ -703,7 +703,7 @@ NOTE:  After executing Step 2 you will see text from Lesson 5.3. Then move
 
 NOTE: You can also read the output of an external command. For example,
 
-        `:r !ls`{vim}
+        `:r !{unix:(ls),win:(dir)}`{vim}
 
       reads the output of the `ls` command and puts it below the cursor.
 
@@ -712,8 +712,8 @@ NOTE: You can also read the output of an external command. For example,
  1. [:!command](:!cmd) executes an external command.
 
      Some useful examples are:
-     `:!ls`{vim}                    - shows a directory listing
-     `:!rm FILENAME`{vim}           - removes file FILENAME
+     `:!{unix:(ls ),win:(dir)}`{vim}                   - shows a directory listing
+     `:!{unix:(rm ),win:(del)} FILENAME`{vim}          - removes file FILENAME
 
  2. [:w](:w) FILENAME              writes the current Neovim file to disk with
                              name FILENAME.
@@ -724,7 +724,7 @@ NOTE: You can also read the output of an external command. For example,
  4. [:r](:r) FILENAME              retrieves disk file FILENAME and puts it
                              below the cursor position.
 
- 5. [:r !dir](:r!)                  reads the output of the dir command and
+ 5. {unix:([:r !ls](:r!) ),win:([:r !dir](:r!))}                  reads the output of the {unix:(ls),win:(dir)} command and
                              puts it below the cursor position.
 
 # Lesson 6.1: THE OPEN COMMAND
@@ -928,7 +928,7 @@ To start using more features create an "init.vim" file.
 
 ** Command line completion with `<C-d>`{normal} and `<Tab>`{normal}. **
 
- 1. List the contents of the current directory: `:!ls`{vim}
+ 1. List the contents of the current directory: `:!{unix:(ls),win:(dir)}`{vim}
 
  2. Type the start of a command: `:e`{vim}
 
diff --git a/test/functional/plugin/tutor_spec.lua b/test/functional/plugin/tutor_spec.lua
new file mode 100644
index 0000000000..5c84db6d4b
--- /dev/null
+++ b/test/functional/plugin/tutor_spec.lua
@@ -0,0 +1,94 @@
+local Screen = require('test.functional.ui.screen')
+local helpers = require('test.functional.helpers')(after_each)
+local clear = helpers.clear
+local command = helpers.command
+local feed = helpers.feed
+local is_os = helpers.is_os
+
+describe(':Tutor', function()
+  before_each(function()
+    clear({ args = { '-u', 'NORC' } })
+    command('set cmdheight=0')
+    command('Tutor')
+  end)
+
+  it('should apply transformation', function()
+    local expected = is_os('win') and [[
+  {0:  }^                                                                              |
+  {0:  } 3. To verify that a file was retrieved, cursor back and notice that there    |
+  {0:  }    are now two copies of Lesson 5.3, the original and the retrieved version. |
+  {0:  }                                                                              |
+  {0:  }{1:NOTE}: You can also read the output of an external command. For example,       |
+  {0:  }                                                                              |
+  {0:  }        :r {4:!}dir                                                               |
+  {0:  }                                                                              |
+  {0:  }      reads the output of the ls command and puts it below the cursor.        |
+  {0:  }                                                                              |
+  {0:  }{3:#}{5: Lesson 5 SUMMARY}                                                            |
+  {0:  }                                                                              |
+  {0:  } 1. {2::!command} executes an external command.                                   |
+  {0:  }                                                                              |
+  {0:  }     Some useful examples are:                                                |
+  {0:  }     :{4:!}dir                   - shows a directory listing                      |
+  {0:  }     :{4:!}del FILENAME          - removes file FILENAME                          |
+  {0:  }                                                                              |
+  {0:  } 2. {2::w} FILENAME              writes the current Neovim file to disk with      |
+  {0:  }                             name FILENAME.                                   |
+  {0:  }                                                                              |
+  {0:  } 3. {2:v}  motion  :w FILENAME   saves the Visually selected lines in file        |
+  {0:  }                             FILENAME.                                        |
+  {0:  }                                                                              |
+  {0:  } 4. {2::r} FILENAME              retrieves disk file FILENAME and puts it         |
+  {0:  }                             below the cursor position.                       |
+  {0:  }                                                                              |
+  {0:  } 5. {2::r !dir}                  reads the output of the dir command and          |
+  {0:  }                             puts it below the cursor position.               |
+  {0:  }                                                                              |
+    ]] or [[
+  {0:  }^                                                                              |
+  {0:  } 3. To verify that a file was retrieved, cursor back and notice that there    |
+  {0:  }    are now two copies of Lesson 5.3, the original and the retrieved version. |
+  {0:  }                                                                              |
+  {0:  }{1:NOTE}: You can also read the output of an external command. For example,       |
+  {0:  }                                                                              |
+  {0:  }        :r {4:!}ls                                                                |
+  {0:  }                                                                              |
+  {0:  }      reads the output of the ls command and puts it below the cursor.        |
+  {0:  }                                                                              |
+  {0:  }{3:#}{5: Lesson 5 SUMMARY}                                                            |
+  {0:  }                                                                              |
+  {0:  } 1. {2::!command} executes an external command.                                   |
+  {0:  }                                                                              |
+  {0:  }     Some useful examples are:                                                |
+  {0:  }     :{4:!}ls                    - shows a directory listing                      |
+  {0:  }     :{4:!}rm  FILENAME          - removes file FILENAME                          |
+  {0:  }                                                                              |
+  {0:  } 2. {2::w} FILENAME              writes the current Neovim file to disk with      |
+  {0:  }                             name FILENAME.                                   |
+  {0:  }                                                                              |
+  {0:  } 3. {2:v}  motion  :w FILENAME   saves the Visually selected lines in file        |
+  {0:  }                             FILENAME.                                        |
+  {0:  }                                                                              |
+  {0:  } 4. {2::r} FILENAME              retrieves disk file FILENAME and puts it         |
+  {0:  }                             below the cursor position.                       |
+  {0:  }                                                                              |
+  {0:  } 5. {2::r !ls}                   reads the output of the ls command and           |
+  {0:  }                             puts it below the cursor position.               |
+  {0:  }                                                                              |
+    ]]
+
+    local screen = Screen.new(80, 30)
+    screen:set_default_attr_ids({
+      [0] = { foreground = Screen.colors.DarkBlue, background = Screen.colors.Gray },
+      [1] = { bold = true },
+      [2] = { underline = true, foreground = tonumber('0x0088ff') },
+      [3] = { foreground = Screen.colors.SlateBlue },
+      [4] = { bold = true, foreground = Screen.colors.Brown },
+      [5] = { bold = true, foreground = Screen.colors.Magenta1 },
+    })
+    screen:attach()
+
+    feed(':700<CR>z<CR>')
+    screen:expect(expected)
+  end)
+end)