doc: document some configuration options (#283)

README.md

@@ -154,9 +154,10 @@ require("oil").setup({
   },
   -- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
   delete_to_trash = false,
-  -- Skip the confirmation popup for simple operations
+  -- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
   skip_confirm_for_simple_edits = false,
   -- Selecting a new/moved/renamed file or directory will prompt you to save changes first
+  -- (:help prompt_save_on_select_new_entry)
   prompt_save_on_select_new_entry = true,
   -- Oil will automatically delete hidden buffers after this delay
   -- You can set the delay to false to disable cleanup entirely

doc/oil.txt

@@ -3,15 +3,16 @@
 --------------------------------------------------------------------------------
 CONTENTS                                                            *oil-contents*
 
-  1. Options                                                     |oil-options|
+  1. Config                                                       |oil-config|
-  2. Api                                                             |oil-api|
+  2. Options                                                     |oil-options|
-  3. Columns                                                     |oil-columns|
+  3. Api                                                             |oil-api|
-  4. Actions                                                     |oil-actions|
+  4. Columns                                                     |oil-columns|
-  5. Highlights                                               |oil-highlights|
+  5. Actions                                                     |oil-actions|
-  6. Trash                                                         |oil-trash|
+  6. Highlights                                               |oil-highlights|
+  7. Trash                                                         |oil-trash|
 
 --------------------------------------------------------------------------------
-OPTIONS                                                              *oil-options*
+CONFIG                                                                *oil-config*
 
 >lua
     require("oil").setup({
@@ -44,9 +45,10 @@ OPTIONS                                                              *oil-option
       },
       -- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
       delete_to_trash = false,
-      -- Skip the confirmation popup for simple operations
+      -- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
       skip_confirm_for_simple_edits = false,
       -- Selecting a new/moved/renamed file or directory will prompt you to save changes first
+      -- (:help prompt_save_on_select_new_entry)
       prompt_save_on_select_new_entry = true,
       -- Oil will automatically delete hidden buffers after this delay
       -- You can set the delay to false to disable cleanup entirely
@@ -160,6 +162,39 @@ OPTIONS                                                              *oil-option
     })
 <
 
+--------------------------------------------------------------------------------
+OPTIONS                                                              *oil-options*
+
+
+skip_confirm_for_simple_edits                  *oil.skip_confirm_for_simple_edits*
+    type: `boolean` default: `false`
+    Before performing filesystem operations, Oil displays a confirmation popup to ensure
+    that all operations are intentional. When this option is `true`, the popup will be
+    skipped if the operations:
+        * contain no deletes
+        * contain no cross-adapter moves or copies (e.g. from local to ssh)
+        * contain at most one copy or move
+        * contain at most five creates
+
+prompt_save_on_select_new_entry              *oil.prompt_save_on_select_new_entry*
+    type: `boolean` default: `true`
+    There are two cases where this option is relevant:
+    1. You copy a file to a new location, then you select it and make edits before
+       saving.
+    2. You copy a directory to a new location, then you enter the directory and make
+       changes before saving.
+
+    In case 1, when you edit the file you are actually editing the original file because
+    oil has not yet moved/copied it to its new location. This means that the original
+    file will, perhaps unexpectedly, also be changed by any edits you make.
+
+    Case 2 is similar; when you edit the directory you are again actually editing the
+    original location of the directory. If you add new files, those files will be
+    created in both the original location and the copied directory.
+
+    When this option is `true`, Oil will prompt you to save before entering a file or
+    directory that is pending within oil, but does not exist on disk.
+
 --------------------------------------------------------------------------------
 API                                                                      *oil-api*
 
@@ -515,7 +550,7 @@ Mac:
     (instead of being able to see files that were trashed from a directory).
 
 Windows:
-    Oil supports the Recycle bin. All features should work.
+    Oil does not yet support the Windows trash. PRs are welcome!
 
 ================================================================================
 vim:tw=80:ts=2:ft=help:norl:syntax=help:

lua/oil/config.lua

@@ -28,9 +28,10 @@ local default_config = {
   },
   -- Send deleted files to the trash instead of permanently deleting them (:help oil-trash)
   delete_to_trash = false,
-  -- Skip the confirmation popup for simple operations
+  -- Skip the confirmation popup for simple operations (:help oil.skip_confirm_for_simple_edits)
   skip_confirm_for_simple_edits = false,
   -- Selecting a new/moved/renamed file or directory will prompt you to save changes first
+  -- (:help prompt_save_on_select_new_entry)
   prompt_save_on_select_new_entry = true,
   -- Oil will automatically delete hidden buffers after this delay
   -- You can set the delay to false to disable cleanup entirely

scripts/generate.py

@@ -164,7 +164,7 @@ COL_DEFS = [
 
 
 def get_options_vimdoc() -> "VimdocSection":
-    section = VimdocSection("options", "oil-options")
+    section = VimdocSection("config", "oil-config")
     config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
     opt_lines = read_section(config_file, r"^local default_config =", r"^}$")
     lines = ["\n", ">lua\n", '    require("oil").setup({\n']
@@ -174,6 +174,43 @@ def get_options_vimdoc() -> "VimdocSection":
     return section
 
 
+def get_options_detail_vimdoc() -> "VimdocSection":
+    section = VimdocSection("options", "oil-options")
+    section.body.append(
+        """
+skip_confirm_for_simple_edits                  *oil.skip_confirm_for_simple_edits*
+    type: `boolean` default: `false`
+    Before performing filesystem operations, Oil displays a confirmation popup to ensure
+    that all operations are intentional. When this option is `true`, the popup will be
+    skipped if the operations:
+        * contain no deletes
+        * contain no cross-adapter moves or copies (e.g. from local to ssh)
+        * contain at most one copy or move
+        * contain at most five creates
+
+prompt_save_on_select_new_entry              *oil.prompt_save_on_select_new_entry*
+    type: `boolean` default: `true`
+    There are two cases where this option is relevant:
+    1. You copy a file to a new location, then you select it and make edits before
+       saving.
+    2. You copy a directory to a new location, then you enter the directory and make
+       changes before saving.
+
+    In case 1, when you edit the file you are actually editing the original file because
+    oil has not yet moved/copied it to its new location. This means that the original
+    file will, perhaps unexpectedly, also be changed by any edits you make.
+
+    Case 2 is similar; when you edit the directory you are again actually editing the
+    original location of the directory. If you add new files, those files will be
+    created in both the original location and the copied directory.
+
+    When this option is `true`, Oil will prompt you to save before entering a file or
+    directory that is pending within oil, but does not exist on disk.
+"""
+    )
+    return section
+
+
 def get_highlights_vimdoc() -> "VimdocSection":
     section = VimdocSection("Highlights", "oil-highlights", ["\n"])
     highlights = read_nvim_json('require("oil")._get_highlights()')
@@ -269,6 +306,7 @@ def generate_vimdoc():
     doc.sections.extend(
         [
             get_options_vimdoc(),
+            get_options_detail_vimdoc(),
             VimdocSection("API", "oil-api", render_vimdoc_api("oil", funcs)),
             get_columns_vimdoc(),
             get_actions_vimdoc(),