From a613a7b5a1554a3d714dba4df8922af45bb8f44b Mon Sep 17 00:00:00 2001
From: kiyan <yazdani.kiyan@protonmail.com>
Date: Sun, 8 May 2022 13:22:49 +0200
Subject: [PATCH] chore(doc): improve help by allowing accessing nested options

---
 README.md             |   1 +
 doc/nvim-tree-lua.txt | 501 ++++++++++++++++++++----------------------
 2 files changed, 242 insertions(+), 260 deletions(-)

diff --git a/README.md b/README.md
index 71efe78dadf..663ba51a1a6 100644
--- a/README.md
+++ b/README.md
@@ -115,6 +115,7 @@ require'nvim-tree'.setup {
 
 -- setup with all defaults
 -- each of these are documented in `:help nvim-tree.OPTION_NAME`
+-- nested options are documented by accessing them with `.` (eg: `:help nvim-tree.view.mappings.list`).
 require'nvim-tree'.setup { -- BEGIN_DEFAULT_OPTS
   auto_reload_on_write = true,
   disable_netrw = false,
diff --git a/doc/nvim-tree-lua.txt b/doc/nvim-tree-lua.txt
index e2e10a4dabe..bf4927f11ee 100644
--- a/doc/nvim-tree-lua.txt
+++ b/doc/nvim-tree-lua.txt
@@ -205,138 +205,121 @@ As options are currently being migrated, configuration of global options in
 Here is a list of the options available in the setup call:
 
 *nvim-tree.disable_netrw*
-- |disable_netrw|: completely disable netrw
-  type: `boolean`
-  default: `false`
+Completely disable netrw
+  Type: `boolean`, Default: `false`
 
 *nvim-tree.hijack_netrw*
-- |hijack_netrw|: hijack netrw windows (overriden if |disable_netrw| is `true`)
-  type: `boolean`
-  default: `true`
+Hijack netrw windows (overriden if |disable_netrw| is `true`)
+  Type: `boolean`, Default: `true`
 
 *nvim-tree.open_on_setup*
-- |open_on_setup|: will automatically open the tree when running setup if
-  startup buffer is a directory, is empty or is unnamed. nvim-tree window will
-  be focused.
-  type: `boolean`
-  default: `false`
+Will automatically open the tree when running setup if startup buffer is
+a directory, is empty or is unnamed. nvim-tree window will be focused.
+  Type: `boolean`, Default: `false`
 
 *nvim-tree.open_on_setup_file*
-- |open_on_setup_file|: will automatically open the tree when running setup if
-  startup buffer is a file. File window will be focused. File will be found if
-  |update_focused_file.enable| is set.
-  type: `boolean`
-  default: `false`
+Will automatically open the tree when running setup if startup buffer is a file.
+File window will be focused.
+File will be found if update_focused_file is enabled.
+  Type: `boolean`, Default: `false`
 
 *nvim-tree.ignore_buffer_on_setup*
-- |ignore_buffer_on_setup|: will ignore the buffer, when deciding to open the tree
-  on setup
-  type: `boolean`
-  default: `false`
+Will ignore the buffer, when deciding to open the tree on setup.
+  Type: `boolean`, Default: `false`
 
 *nvim-tree.ignore_ft_on_setup*
-- |ignore_ft_on_setup|: list of filetypes that will make |open_on_setup| not
-  open. You can use this option if you don't want the tree to open in some
-  scenarios (eg using vim startify).
-  type: `{string}`
-  default: `{}`
+List of filetypes that will make `open_on_setup` not open. 
+You can use this option if you don't want the tree to open
+in some scenarios (eg using vim startify).
+  Type: {string}, Default: {}
 
 *nvim-tree.auto_reload_on_write*
-- |auto_reload_on_write|: reloads the explorer every time a buffer is written to
-  type: `boolean`
-  default: `true`
+Reloads the explorer every time a buffer is written to.
+  Type: `boolean`, Default: `true`
 
 *nvim-tree.open_on_tab*
-- |open_on_tab|: opens the tree automatically when switching tabpage or opening a new
-  tabpage if the tree was previously open.
-  type: `boolean`
-  default: `false`
+Opens the tree automatically when switching tabpage or opening a new tabpage
+if the tree was previously open.
+  Type: `boolean`, Default: `false`
 
 *nvim-tree.sort_by*
-- |sort_by|: changes how files within the same directory are sorted. can be
-  one of 'name' | 'case_sensitive' | 'modification_time'.
-  type: `string`
-  default: `"name"`
+Changes how files within the same directory are sorted.
+Can be one of 'name', 'case_sensitive' or 'modification_time'.
+  Type: `string`, Default: `"name"`
 
 *nvim-tree.hijack_unnamed_buffer_when_opening*
-- |hijack_unnamed_buffer_when_opening|: opens in place of the unnamed
-  buffer if it's empty.
-  type: `boolean`
-  default: `false`
+Opens in place of the unnamed buffer if it's empty.
+  Type: `boolean`, Default: `false`
 
-*nvim-tree.hijack_directories*
-- |hijack_directories|: hijacks new directory buffers when they are opened (`:e dir`).
+*nvim-tree.hijack_cursor*
+Keeps the cursor on the first letter of the filename when moving in the tree.
+  Type: `boolean`, Default: `false`
 
-  - |hijack_directories.enable|: enable the feature. Disable this option if you
-    use vim-dirvish or dirbuf.nvim. If |hijack_netrw| and |disable_netrw| are
-    `false`, this feature will be disabled.
-    type: `boolean`
-    default: `true`
+*nvim-tree.update_cwd*
+Changes the tree root directory on `DirChanged` and refreshes the tree.
+  Type: `boolean`, Default: `false`
 
-  - |hijack_directories.auto_open|: opens the tree if the tree was previously closed.
-    type: `boolean`
-    default: `true`
+*nvim-tree.hijack_directories*
+hijacks new directory buffers when they are opened (`:e dir`).
 
-*nvim-tree.hijack_cursor*
-- |hijack_cursor|: keeps the cursor on the first letter of the filename when
-  moving in the tree.
-  type: `boolean`
-  default: `false`
+    *nvim-tree.hijack_directories.enable*
+    Enable the feature.
+    Disable this option if you use vim-dirvish or dirbuf.nvim.
+    If `hijack_netrw` and `disable_netrw` are `false`, this feature will be disabled.
+      Type: `boolean`, Default: `true`
 
-*nvim-tree.update_cwd*
-- |update_cwd|: changes the tree root directory on `DirChanged` and refreshes
-  the tree.
-  type: `boolean`
-  default: `false`
+    *nvim-tree.hijack_directories.auto_open*
+    Opens the tree if the tree was previously closed.
+      Type: `boolean`, Default: `true`
 
 *nvim-tree.update_focused_file*
-- |update_focused_file|: update the focused file on `BufEnter`, un-collapses
-  the folders recursively until it finds the file
-
-  - |update_focused_file.enable|: enable this feature.
-    type: `boolean`
-    default: `false`
-
-  - |update_focused_file.update_cwd|: update the root directory of the tree to the one
-    of the folder containing the file if the file is not under the current root
-    directory. Only relevant when |update_focused_file.enable| is `true`
-    type: `boolean`
-    default: `false`
-
-  - |update_focused_file.ignore_list|: list of buffer names and filetypes that will not
-    update the root dir of the tree if the file isn't found under the current root
-    directory. Only relevant when |update_focused_file.update_cwd| is `true` and
-    |update_focused_file.enable| is `true`.
-    type: `{string}`
-    default: `{}`
+Update the focused file on `BufEnter`, un-collapses the folders recursively
+until it finds the file.
+
+    *nvim-tree.update_focused_file.enable*
+    Enable this feature.
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.update_focused_file.update_cwd*
+    Update the root directory of the tree to the one of the folder containing
+    the file if the file is not under the current root directory.
+    Only relevant when `update_focused_file.enable` is `true`
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.update_focused_file.ignore_list*
+    List of buffer names and filetypes that will not update the root dir
+    of the tree if the file isn't found under the current root directory.
+    Only relevant when `update_focused_file.update_cwd` and
+    `update_focused_file.enable` are `true`.
+      Type: {string}, Default: {}
 
 *nvim-tree.system_open*
-- |system_open|: configuration options for the system open command
+Configuration options for the system open command.
 
-  - |system_open.cmd|: the command to run, leaving empty should work but
-    useful if you want to override the default command with another one.
-    type: `string`
-    default: `""`
+    *nvim-tree.system_open.cmd*
+    The command to run, leaving empty should work but useful if you want to
+    override the default command with another one.
+      Type: `string`, Default: `""`
 
-  - |system_open.args|: the command arguments as a list
-    type: `{string}`
-    default: `{}`
+    *nvim-tree.system_open.args*
+    The command arguments as a list.
+      Type: {string}, Default: {}
 
 *nvim-tree.diagnostics*
-- |diagnostics|: show lsp diagnostics in the signcolumn
+Show lsp diagnostics in the signcolumn
 
-  - |diagnostics.enable|: enable/disable the feature
-      type: `boolean`
-      default: `false`
+    *nvim-tree.diagnostics.enable*
+    Enable/disable the feature.
+      Type: `boolean`, Default: `false`
 
-  - |diagnostics.show_on_dirs|: if the node with diagnostic is not visible,
-    then show diagnostic in the parent directory
-      type: `boolean`
-      default: `false`
+    *nvim-tree.diagnostics.show_on_dirs*
+    If the node with diagnostic is not visible, then show diagnostic in the
+    parent directory.
+      Type: `boolean`, Default: `false`
 
-  - |diagnostics.icons|: icons for diagnostic severity
-      type: `table`
-      default: `{ hint = "", info = "", warning = "", error = "" }`
+    *nvim-tree.diagnostics.icons*
+    Icons for diagnostic severity.
+      Type: {}, Default: { hint = "", info = "", warning = "", error = "" }
 
     `NOTE`: it will use the default diagnostic color groups to highlight the signs.
     If you wish to customize, you can override these groups:
@@ -346,20 +329,20 @@ Here is a list of the options available in the setup call:
     - `NvimTreeLspDiagnosticsHint`
 
 *nvim-tree.git*
-- |git|: git integration with icons and colors
+Git integration with icons and colors.
 
-  - |git.enable|: enable / disable the feature
-      type: `boolean`
-      default: `true`
+    *nvim-tree.git.enable*
+    Enable / disable the feature.
+      Type: `boolean`, Default: `true`
 
-  - |git.ignore|: ignore files based on `.gitignore`
+    *nvim-tree.git.ignore*
+    Ignore files based on `.gitignore`.
     Toggle via the `toggle_git_ignored` action, default mapping `I`.
-      type: `boolean`
-      default: `true`
+      Type: `boolean`, Default: `true`
 
-  - |git.timeout|: kills the git process after some time if it takes too long
-      type: `number`
-      default: `400` (ms)
+    *nvim-tree.git.timeout*
+    Kills the git process after some time if it takes too long.
+      Type: `number`, Default: `400` (ms)
 
   You will still need to configure `g:nvim_tree_show_icons.git` or
   `g:nvim_tree_git_hl` to be able to see things in the tree. This will be
@@ -372,203 +355,201 @@ Here is a list of the options available in the setup call:
   process returned the data.
 
 *nvim-tree.view*
-- |view|: window / buffer setup
+Window / buffer setup.
 
-  - |view.hide_root_folder|: hide the path of the current working
-    directory on top of the tree
-      type: `boolean`
-      default: `false`
+    *nvim-tree.view.hide_root_folder*
+    Hide the path of the current working directory on top of the tree.
+      Type: `boolean`, Default: `false`
 
-  - |view.width|: width of the window, can be either a `%` string or
-    a number representing columns. Only works with |view.side| `left` or `right`
-      type: `string | number`
-      default: `30`
+    *nvim-tree.view.width*
+    Width of the window, can be either a `%` string or a number representing columns.
+    Only works with `side` is `left` or `right`.
+      Type: `string | number`, Default: `30`
 
-  - |view.height|: height of the window, can be either a `%` string or
-    a number representing rows. Only works with |view.side| `top` or `bottom`
-      type: `string | number`
-      default: `30`
+    *nvim-tree.view.height*
+    Height of the window, can be either a `%` string or a number representing rows.
+    Only works with  `side` is `top` or `bottom`
+      Type: `string | number`, Default: `30`
 
-  - |view.side|: side of the tree, can be one of 'left' | 'right' | 'bottom' | 'top'
+    *nvim-tree.view.side*
+    Side of the tree, can be one of 'left' | 'right' | 'bottom' | 'top'.
     Note that bottom/top are not working correctly yet.
-      type: `string`
-      default: 'left'
-
-  - |view.preserve_window_proportions|: preserve window proportions when
-    opening a file. If `false`, the height and width of windows other than
-    nvim-tree will be equalized.
-      type: `boolean`
-      default: `false`
-
-  - |view.number|: print the line number in front of each line.
-      type: `boolean`
-      default: `false`
-
-  - |view.relativenumber|: show the line number relative to the line with the
-    cursor in front of each line. If the option `view.number` is also `true`,
-    the number on the cursor line will be the line number instead of `0`.
-      type: `boolean`
-      default: `false`
-
-  - |view.signcolumn|: show diagnostic sign column. Value can be `"yes"`,
-    `"auto"`, `"no"`
-      type: `string`
-      default: `"yes"`
-
-  - |view.mappings|: configuration options for keymaps
-
-    - |view.mappings.custom_only|: will use only the provided user mappings and not the default
-      otherwise, extends the default mappings with the provided user mappings
-        type: `boolean`
-        default: `false`
-
-    - |view.mappings.list|: a list of keymaps that will extend or override the default keymaps
-        type: list of `{ key: table of strings or string, mode: string (vim-mode), cb: callback function as a string }`
-        default: `{}`
+      Type: `string`, Default: 'left'
+
+    *nvim-tree.view.preserve_window_proportions*
+    Preserves window proportions when opening a file.
+    If `false`, the height and width of windows other than nvim-tree will be equalized.
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.view.number*
+    Print the line number in front of each line.
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.view.relativenumber*
+    Show the line number relative to the line with the cursor in front of each line.
+    If the option `view.number` is also `true`, the number on the cursor line
+    will be the line number instead of `0`.
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.view.signcolumn*
+    Show diagnostic sign column. Value can be `"yes"`, `"auto"`, `"no"`.
+      Type: `string`, Default: `"yes"`
+
+    *nvim-tree.view.mappings*
+    Configuration options for keymaps
+
+	*nvim-tree.view.mappings.custom_only*
+      	Will use only the provided user mappings and not the default otherwise,
+      	extends the default mappings with the provided user mappings.
+      	  Type: `boolean`, Default: `false`
+  
+	*nvim-tree.view.mappings.list*
+	A list of keymaps that will extend or override the default keymaps.
+	  Type: list of { key: table of strings or string, mode: string (vim-mode), cb: callback function as a string }
+	  Default: {}
 
 *nvim-tree.renderer*
-- |renderer|: UI rendering setup
+UI rendering setup
 
-  - |renderer.indent_markers|: configuration options for tree indent markers
+    *nvim-tree.renderer.indent_markers*
+    Configuration options for tree indent markers.
 
-    - |renderer.indent_markers.enable|: display indent markers when folders are open
-        type: `boolean`
-        default: `false`
+	*nvim-tree.renderer.indent_markers.enable*
+	Display indent markers when folders are open
+          Type: `boolean`, Default: `false`
 
-    - |renderer.indent_markers.icons|: icons shown before the file/directory
-        type: `table`
-	default: `{ corner = "└ ", edge = "│ ", none = "  ", }`
+	*nvim-tree.renderer.indent_markers.icons*
+	Icons shown before the file/directory.
+          Type: `table`, Default: `{ corner = "└ ", edge = "│ ", none = "  ", }`
 
-  - |renderer.icons|: configuration options for icons
+    *nvim-tree.renderer.icons*
+    Configuration options for icons.
 
-    - |renderer.icons.webdev_colors|: use the webdev icon colors, otherwise `NvimTreeFileIcon`.
-        type: `boolean`
-        default: `true`
+	*nvim-tree.renderer.icons.webdev_colors*
+	Use the webdev icon colors, otherwise `NvimTreeFileIcon`.
+          Type: `boolean`, Default: `true`
 
-    - |renderer.icons.git_placement|: place where the git icons will be rendered.
+	*nvim-tree.renderer.icons.git_placement*
+	Place where the git icons will be rendered.
 	After or before the `filename` (after the file/folders icons).
-	type: `after` or `before`
-	default: `before`
+	  Type: `after` or `before`, Default: `before`
 
 *nvim-tree.filters*
-|filters|: filtering options
+Filtering options.
 
-  - |filters.dotfiles|: do not show dotfiles: files starting with a `.`
+    *nvim-tree.filters.dotfiles*
+    Do not show dotfiles: files starting with a `.`
     Toggle via the `toggle_dotfiles` action, default mapping `H`.
-      type: `boolean`
-      default: `false`
+      Type: `boolean`, Default: `false`
 
-  - |filters.custom|: custom list of vim regex for file/directory names that will not be shown.
+    *nvim-tree.filters.custom*
+    Custom list of vim regex for file/directory names that will not be shown.
     Backslashes must be escaped e.g. "^\\.git". See |string-match|.
     Toggle via the `toggle_custom` action, default mapping `U`.
-      type: `{string}`
-      default: `{}`
+      Type: {string}, Default: {}
 
-  - |filters.exclude|: list of directories or files to exclude from filtering: always show them.
+    *nvim-tree.filters.exclude*
+    List of directories or files to exclude from filtering: always show them.
     Overrides `git.ignore`, `filters.dotfiles` and `filters.custom`.
-      type: `{string}`
-      default: `{}`
+      Type: {string}, Default: {}
 
 *nvim-tree.trash*
-|trash|: configuration options for trashing
+Configuration options for trashing.
 
-  - |trash.cmd|: the command used to trash items (must be installed on your system)
-      type: `string`
-      default: `"trash"`
+    *nvim-tree.trash.cmd*
+    The command used to trash items (must be installed on your system).
+      Type: `string`, Default: `"trash"`
 
-  - |trash.require_confirm|: show a prompt before trashing takes place.
-      type: `boolean`
-      default: `true`
+    *nvim-tree.trash.require_confirm*
+    Show a prompt before trashing takes place.
+      Type: `boolean`, Default: `true`
 
 *nvim-tree.actions*
-|actions|: configuration for various actions
+Configuration for various actions.
 
-  - |actions.change_dir.enable|: change the working directory when changing
-    directories in the tree.
-      type: `boolean`
-      default: `true`
+    *nvim-tree.actions.change_dir.enable*
+    Change the working directory when changing directories in the tree.
+      Type: `boolean`, Default: `true`
 
-  - |actions.change_dir.global|: use `:cd` instead of `:lcd` when changing
-    directories. Consider that this might cause issues with
-    the |update_cwd| options.
-      type: `boolean`
-      default: `false`
+    *nvim-tree.actions.change_dir.global*
+    Use `:cd` instead of `:lcd` when changing directories.
+    Consider that this might cause issues with the `update_cwd` options.
+      Type: `boolean`, Default: `false`
 
-  - |actions.change_dir.restrict_above_cwd|: restrict changing to a directory
-    above the global current working directory.
-      type: `boolean`
-      default: `false`
+    *nvim-tree.actions.change_dir.restrict_above_cwd*
+    Restrict changing to a directory above the global current working directory.
+      Type: `boolean`, Default: `false`
 
-  - |actions.open_file.quit_on_open|: closes the explorer when opening a file.
+    *nvim-tree.actions.open_file.quit_on_open*
+    Closes the explorer when opening a file.
     It will also disable preventing a buffer overriding the tree.
-      type: `boolean`
-      default: `false`
-
-  - |actions.open_file.resize_window|: resizes the tree when opening a file
-      type: `boolean`
-      default: `false`
-
-  - |actions.open_file.window_picker|: window picker configuration
-
-    - |actions.open_file.window_picker.enable|: Enable the feature. If the
-      feature is not enabled, files will open in window from which you
-      last opened the tree.
-	type: `boolean`
-	default: `true`
-
-    - |actions.open_file.window_picker.chars|: A string of chars used as
-      identifiers by the window picker.
-	type: `string`
-	default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`
-
-    - |actions.open_file.window_picker.exclude|: Table of buffer option names
-      mapped to a list of option values that indicates to the picker that the
-      buffer's window should not be selectable.
-	type: `table`
-	default: `{`
-			`filetype = { "notify", "packer", "qf", "diff", "fugitive", "fugitiveblame", },`
-			`buftype  = { "nofile", "terminal", "help", }`
-		`}`
-
-    - |actions.use_system_clipboard|: A boolean value that toggle the use of system clipboard
-      when copy/paste function are invoked.
-      When enabled, copied text will be stored in registers '+' (system), otherwise, it will be stored in '1' and '"'.
-	type: `boolean`
-	default: `true`
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.actions.open_file.resize_window*
+    Resizes the tree when opening a file.
+      Type: `boolean`, Default: `false`
+
+    *nvim-tree.actions.open_file.window_picker*
+    Window picker configuration.
+
+	*nvim-tree.actions.open_file.window_picker.enable*
+	Enable the feature. If the feature is not enabled, files will open in window
+	from which you last opened the tree.
+	  Type: `boolean`, Default: `true`
+
+	*nvim-tree.actions.open_file.window_picker.chars*
+	A string of chars used as identifiers by the window picker.
+	  Type: `string`, Default: `"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890"`
+
+	*nvim-tree.actions.open_file.window_picker.exclude*
+	Table of buffer option names mapped to a list of option values that indicates
+	to the picker that the buffer's window should not be selectable.
+	  Type: `table`
+	  Default: {
+		     `filetype = { "notify", "packer", "qf", "diff", "fugitive", "fugitiveblame", },`
+		     `buftype  = { "nofile", "terminal", "help", }`
+		   }
+
+    *nvim-tree.actions.use_system_clipboard*
+    A boolean value that toggle the use of system clipboard when copy/paste
+    function are invoked. When enabled, copied text will be stored in registers
+    '+' (system), otherwise, it will be stored in '1' and '"'.
+      Type: `boolean`, Default: `true`
 
 
 *nvim-tree.log*
-|log|: configuration for diagnostic logging
+Configuration for diagnostic logging.
 
-  - |log.enable|: enable logging to a file `$XDG_CACHE_HOME/nvim/nvim-tree.log`
-      type: `boolean`
-      default: `false`
+    *nvim-tree.log.enable*
+    Enable logging to a file `$XDG_CACHE_HOME/nvim/nvim-tree.log`
+      Type: `boolean`, Default: `false`
 
-  - |log.truncate|: remove existing log file at startup
-      type: `boolean`
-      default: `false`
+    *nvim-tree.log.truncate*
+    Remove existing log file at startup.
+      Type: `boolean`, Default: `false`
 
-  - |log.types|: specify which information to log
+    *nvim-tree.log.types*
+    Specify which information to log.
 
-    - |log.types.all|: everything
-        type: `boolean`
-        default: `false`
+	*nvim-tree.log.types.all*
+	Everything.
+          Type: `boolean`, Default: `false`
 
-    - |log.types.profile|: timing of some operations
-        type: `boolean`
-        default: `false`
+	*nvim-tree.log.types.profile*
+	Timing of some operations.
+          Type: `boolean`, Default: `false`
 
-    - |log.types.config|: options and mappings, at startup
-        type: `boolean`
-        default: `false`
+	*nvim-tree.log.types.config*
+	Options and mappings, at startup.
+          Type: `boolean`, Default: `false`
 
-    - |log.types.copy_paste|: file copy and paste actions
-        type: `boolean`
-        default: `false`
+	*nvim-tree.log.types.copy_paste*
+	File copy and paste actions.
+          Type: `boolean`, Default: `false`
 
-    - |log.types.git|: git processing
-        type: `boolean`
-        default: `false`
+	*nvim-tree.log.types.git*
+	Git processing.
+          Type: `boolean`, Default: `false`
 
 ==============================================================================
 OPTIONS				                  *nvim-tree-options*