From 0d55d260ade343de4f197d38eaccaf442fd66f2b Mon Sep 17 00:00:00 2001
From: John Practicalli <250870+practicalli-john@users.noreply.github.com>
Date: Thu, 5 Oct 2023 12:04:01 +0100
Subject: [PATCH] basics: rename file buffer window tab & refactor content

- rename file to match new title
- update mkdocs.yml navigation
- reorganise page sections
- enhance clarity of each section, remove duplication
---
 ...s-windows.md => file-buffer-window-tab.md} | 107 ++++++++++--------
 mkdocs.yml                                    |   2 +-
 2 files changed, 58 insertions(+), 51 deletions(-)
 rename docs/neovim-basics/{files-buffers-windows.md => file-buffer-window-tab.md} (78%)

diff --git a/docs/neovim-basics/files-buffers-windows.md b/docs/neovim-basics/file-buffer-window-tab.md
similarity index 78%
rename from docs/neovim-basics/files-buffers-windows.md
rename to docs/neovim-basics/file-buffer-window-tab.md
index 06347236..4a72c7e0 100644
--- a/docs/neovim-basics/files-buffers-windows.md
+++ b/docs/neovim-basics/file-buffer-window-tab.md
@@ -1,48 +1,84 @@
 # Files Buffers Windows and Tabs
 
-Buffers hold the contents of files and any other information from processes, e.g. the REPL evaluation log
+[Files](#files) are text written to perminant storage, e.g. disk or usb drive and are names with an extension that represents the file type, e.g. `.clj` for clojure, `.md` for markdown, etc.
 
-Windows are a container for a buffer and windows can swap which buffer they show.  Multiple windows, also known as splits, can be present in a Neovim frame.  By default, neovim starts with only one window.
+A [Buffer](#buffers) hold the contents of a file or any other information from processes, e.g. the REPL evaluation log.
 
-A tab can hold one or more windows and tabs can be shown on a tab-line. ++"g"++ ++"T"++ toggles between tabs, e.g. Clojure source code and Clojure Log
+[Windows](#windows) are a view on a buffer and windows can swap which buffer they show.  Multiple windows, also known as splits, can be present in a Neovim frame.  
 
+A [tab page](#tab-pages) (or tab) can hold one or more windows and multiple tab pages can be shown on a tab-line. 
 
-## File explorer
 
-Visually manage files with a tree view of the current project, using [:fontawesome-brands-github: Neo-tree.nvim](https://github.com/nvim-neo-tree/neo-tree.nvim){target=_blank}
+## Files
 
+Use [Neo-tree.nvim](#using-neo-tree) to visually navigate and manage files using a tree view of the current project. Files and directories can be added, renamed, moved and deleted.
+
+Use [Telescope](#telescope) to select files, typing a name narrows the file list.
+
+
+### Using Neo-tree
 
 === "Astronvim"
     ++spc++ ++"e"++ toggles neo-tree file browser
 
     ++spc++ ++"o"++ toggles between buffer and neo-tree
 
-    Neotree icons
 
+=== "Practicalli Neovim Config Redux"
+
+    ++spc++ ++"f"++ ++"t"++ ++"t"++ to open file explorer
+
+Within Neo-tree:
+
+++"h"++ ++"j"++ ++"k"++ ++"l"++ to navigate the file tree hierachy
+
+++less-than++ and ++greater-than++ to navigate between File, Bufs and Git sources tabs
+
+++question-mark++ shows neotree help, listing key bindings
+
+++"a"++ adds a file, prompting for a name relative to the directory where ++"a"++ was pressed. The name can include new directories to be created. A name ending with ++forward-slash++ will create a directory rather than a file.
+
+++"d"++ deletes the current file or directory (including sub-directories), a conformation prompt is shown
+
+++"r"++ to rename a file or directory (use move to change the path)
+
+++"m"++ to move a file or directory, optionally renaming too
+
+!!! INFO "Neotree icons"
     - yellow dot - unsaved changes
     - pencil - git added changes
     - cross - git deleted changes
     - Warning triangle - lsp diagnostics issues
 
-    ++"h"++ ++"j"++ ++"k"++ ++"l"++ to navigate the file tree hierachy
 
-    `<` and `>` to navigate between File, Bufs and Git sources tabs
+### Telescope
 
-    ++question-mark++ shows neotree help, listing key bindings
+Telescope provides a selector which will narrow the list of matches as a pattern is typed, providing a fast way to find an item in a list.
+
+Telescope provides a preview of the selected file (only if there is sufficient space in the Neovim frame)
+
+File lists are relative to the directory Neovim was opened from (or Path subsequently set in Neovim).
+
+=== "AstroNvim"
 
+    `SPC f f` selector for files within the scope of the current directory path. `SPC f F` to also show hidden files from the current directory path. 
+    
+    `SPC f a` selector for AstroNvim user configuration files
+
+    `SPC f p` selector for previously opened files (oldfiles)
 
 === "Practicalli Neovim Config Redux"
+    `SPC f f` to list files within the scope of the current directory path.
+
+    `SPC f b` provides a file browser to open files, navigate the file space and create new files and directories
 
-    ++spc++ ++"f"++ ++"t"++ ++"t"++ to open file explorer
 
 
-## New File
+### Save File
 
 Files and directories are created in the path given, relative to the directory in which Neovim was opened.
 
-> `:lcd` to set the current local directory
->  
-> `:!` for a shell command, e.g. `:!mkdir -p path/to/new/directory` create a new directory and any intermediate path
+A file must exist for Neovim to write to it.  Neo-tree and Telescope can be used to create files and directories, as can a terminal and the command line integration (++exclamation++)
 
 
 === "Astronvim"
@@ -52,16 +88,6 @@ Files and directories are created in the path given, relative to the directory i
 
     `:write path/to/filename` will write the current buffer to a new file.
 
-    Use Neotree as a convienient way to create, rename, move and delete files and directories
-
-    ++"a"++ to add a file using the given name, or directory if the name ends in a `/`
-
-    ++"m"++ to move a file or directory
-
-    ++"r"++ to rename a file or directory
-
-    ++"d"++ to delete a file or directory, showing a confirmation prompt first
-
 
 === "Practicalli Neovim Config Redux"
 
@@ -74,6 +100,8 @@ Files and directories are created in the path given, relative to the directory i
 
 === "Neovim"
 
+    `:lcd` to set the current local directory
+
     `:write path/to/filename` will write the current buffer to a new file
 
     `:!mkdir path/to/directory` will create a new directory
@@ -88,29 +116,8 @@ Files and directories are created in the path given, relative to the directory i
 
      `:h` for the current directory (the “head” of the path).
 
-     `!` is the NeoVim terminal shell command
-
-
-## Select files and directories
-
-Telescope provides a selector which will narrow the list of matches as a pattern is typed, providing a fast way to find an item in a list.
-
-Telescope provides a preview of the selected file (only if there is sufficient space in the Neovim frame)
-
-File lists are relative to the directory Neovim was opened from (or Path subsequently set in Neovim).
-
-=== "AstroNvim"
-
-    `SPC f f` selector for files within the scope of the current directory path. `SPC f F` to also show hidden files from the current directory path. 
-    
-    `SPC f a` selector for AstroNvim user configuration files
-
-    `SPC f p` selector for previously opened files (oldfiles)
+     `!` is the NeoVim terminal shell command, e.g. `:!mkdir -p path/to/new/directory` creates a new directory and any intermediate path
 
-=== "Practicalli Neovim Config Redux"
-    `SPC f f` to list files within the scope of the current directory path.
-
-    `SPC f b` provides a file browser to open files, navigate the file space and create new files and directories
 
 
 ### Swap file
@@ -137,7 +144,7 @@ Opening a file checks if there is an associated swap file and prompts the user
 > `:edit` after the file is open also prompts if there is a swap file.  Selecting (D)elete will delete the swap file without changing the current buffer
 
 
-## Buffer management
+## Buffers
 
 === "AstroNvim"
 
@@ -173,7 +180,7 @@ Opening a file checks if there is an associated swap file and prompts the user
     nvim README.md deps.edn src/practicalli/playground.clj test/practicalli/playground.clj
     ```
 
-## Buffer text wrapping
+### Buffer text wrapping
 
 The test in a buffer is not wrapped by default. Set and unset soft text wrapping in a buffer
 
@@ -193,7 +200,7 @@ The test in a buffer is not wrapped by default. Set and unset soft text wrapping
     `:set nowrap` to show lines in full (scroll sideways to see lines longer than the window)
 
 
-## Window management
+## Windows 
 
 Windows can be active (contains the cursor), hidden (open but not shown) or inactive.
 
@@ -254,7 +261,7 @@ A Tab page holds one or more windows, each window is a view on a buffer, a buffe
 
 A tab page can provide a logical grouping of windows, e.g. Clojure source code in one tab, tests in a second tab and REPL log in a third.
 
-Neovim commands may be constrained within the bounds of a tab page (without using the :tab modifier)
+Neovim window commands may be constrained within the bounds of a tab page (without using the :tab modifier)
 
 Tab pages are often referred to as tabs.
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 6045d58c..7c0f6f3e 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -154,7 +154,7 @@ nav:
               - Treesitter: configuration/practicalli/packages/nvim-treesitter.md
   - Neovim Basics:
       - neovim-basics/index.md
-      - File Buffer Window: neovim-basics/files-buffers-windows.md
+      - File Buffer Window Tab: neovim-basics/file-buffer-window-tab.md
       - Multi-modal Editing: neovim-basics/multi-modal-editing.md
       - Search Replace: neovim-basics/search-replace.md
       - Comments: neovim-basics/comments.md