docs(ALL): tweak help files for better portability

Details:
- Rename 'mini.txt' into 'mini-nvim.txt' (MINI is a wider project name).

- Make more friendly for the future "convert to markdown" script:
    - Use list in `---@seealso`. Otherwise many lines are parsed as one.
    - Make sure to always explicitly close code block. Otherwise content
      will not be parsed properly.
    - Use exact tag when linking (like |:colorscheme| and not
      |colorscheme|, |'termguicolors'| and not |termguicolors|).
      Otherwise links to neovim.io documentation don't work.
    - Don't use explicit right aligned *tag-anchors* as they result into
      high level heading. It *might* be possible to smartly compute
      heading level (like "high if after `---`, otherwise search up for
      the current level and add one to it"), but it seems to overly
      complex.

- Improve config documentation:
    - Start with "# Defaults ~" title.
    - Don't add extra title to group config field descriptions. Instead
      add "# Setting ~" and "## Subsetting ~" title if necessary.
      Other titles are also allowed, like "# Examples ~" (usually after
      describing all config fields).

- Improve highlight group listing inside module:
    - Use `-` and not `*` for consistency with any other list.
    - Recommend `nvim_set_hl()` instead of `:highlight`.

- Use Markdown style links to link to mentioned plugins. This is helpful
  in both built-in help (with `gx` / `gX`) and site (renders as link).

- Extract first lines (needed for working `:h local-additions` and
  showing license) into a separate comment block. Use alternative
  CamelCase module tag in next comment block with module overview.
  This makes final rendered markdown look better while extra right
  aligned tag adds an entry in table of contents.

- Don't have too indented text (4 spaces and more) outside of nested
  list, as those are parsed as code blocks.

- Reorganize glossaries to use `TERM ~` section starts instead of
  aligned text. This also makes it more markdown friendly (because
  too much indented text outside of lists is parsed as a code block).

- Use `<Word-to-highlight>` convention to add highlight to word
  combinations that need to stand out (like step names inside list).
  This will highlight it both in help and on site.

- Use `|mini.xxx|` to link to a whole module instead of `|MiniXxx|`.
  Mostly because the former is the module's actual name.

- Various small tweaks to wording for better portability. Like prefer to
  not use |`<| tag link as it doesn't work well with inline code block
  detection.

Author: echasnovski

MAINTAINING.md

@@ -15,6 +15,26 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for how to generate help files, run tests
     - There was an intended change in Neovim Nightly to which affected module(s) should adapt. Update module and/or tests.
     - There was a change in Neovim Nightly disrupting only tests (usually screenshots due to changed way of how highlight attributes are computed). Update test: ideally so that it passes on all versions (by adjusting test logic or by selectively ignoring attributes / text of not matching lines with `ignore_text` / `ignore_attr` *behind narrowest Neovim version check*), but testing some parts only on Nightly is allowed if needed (regenerate screenshot on Nightly and verify it only on versions starting from it).
     - There was an unintended change in Neovim Nightly which breaks functionality it should not break. Create an issue in ['neovim/neovim' repo](https://github.com/neovim/neovim). If the issue is not resolved for a long-ish time (i.e. more than a week) try to make tests pass and/or adapt the code to new behavior.
+- Write help annotations in a way that after help generation they are usable in both built-in `:help`and on nvim-mini.org site. In particular:
+    - Prefer using `# Section ~` and `## Subsection ~` explicit sections. This allows more structured table of contents and adds anchors for all of them.
+    - Prefer using "naturally sounding" help tags for an entire section because they are transformed into a title. So like `---@tag MiniAi-builtin-textobjects` and not `---@tag MiniAi-textobjects-builtin`.
+        - As a consequence, don't add "# Title ~" title at the beginning of the section. This is a role for the tag (in both help file and site).
+    - Do not use explicit right aligned tags, as they result into a separate high level heading on the site. This usually breaks hierarchical structure of the page (like if added as part of a `MiniXxx.config` section, it ends the `config` section and starts its own). Prefer to "naturally" incorporate a tag into a text in first line of its info or add it directly below a dedicated section. Examples:
+
+        ```
+        --- # Important topic ~
+        --- *MiniXxx-important-topic*
+        ---
+        --- A text about important topic of 'mini.xxx' module.
+        ---
+        --- # Another topic ~
+        ---
+        --- *MiniXxx-another-topic* is also important.
+        ---
+        --- *MiniXxx-last-resort*
+        --- As last resort just add left aligned tag before first line
+        --- or at line start.
+        ```
 
 ## Maintainer setup
 

README.md

@@ -1,5 +1,7 @@
 <p align="center"> <img src="logo.png" alt="mini.nvim" style="max-width:100%;border:solid 2px"/> </p>
 
+### All-in-one plugin
+
 Library of 40+ independent Lua modules improving overall [Neovim](https://github.com/neovim/neovim) (version 0.9 and higher) experience with minimal effort. They all share same configuration approaches and general design principles.
 
 Think about this project as "Swiss Army knife" among Neovim plugins: it has many different independent tools (modules) suitable for most common tasks. Each module can be used separately without any startup and usage overhead.
@@ -73,7 +75,9 @@ end
 
 ## Modules
 
-'mini.nvim' contains many modules which is slightly daunting at first. All of them can be used independently, one at a time. For easier exploration, here they are presented in groups based on module's primary functionality (although some modules can fit in several groups).
+'mini.nvim' contains many modules which is slightly daunting at first. All of them can be used independently, one at a time.
+
+For easier exploration, here they are presented in groups based on module's primary functionality (although some modules can fit in several groups). See more detailed listing [here](doc/mini-nvim.txt).
 
 ### Text editing
 
@@ -148,36 +152,57 @@ These modules don't quite fit in any of the previous categories.
 
 ## General principles
 
-- **Design**. Each module is designed to solve a particular problem targeting balance between feature-richness (handling as many edge-cases as possible) and simplicity of implementation/support. Granted, not all of them ended up with the same balance, but it is the goal nevertheless.
+### Design
+
+Each module is designed to solve a particular problem targeting balance between feature-richness (handling as many edge-cases as possible) and simplicity of implementation/support. Granted, not all of them ended up with the same balance, but it is the goal nevertheless.
+
+### Independence
+
+Modules are independent of each other and can be run without external dependencies. Although some of them may need dependencies for full experience.
+
+### Structure
+
+Each module is a submodule for a placeholder "mini" module. So, for example, "surround" module should be referred to as "mini.surround".  As later will be explained, this plugin can also be referred to as "MiniSurround".
+
+### Setup
+
+- Each module you want to use should be enabled separately with `require(<name of module>).setup({})`. Possibly replace `{}` with your config table or omit altogether to use defaults. You can supply only parts of config, the rest will be inferred from defaults.
+
+- Call to module's `setup()` always creates a global Lua object with coherent camel-case name: `require('mini.surround').setup()` creates `_G.MiniSurround`. This allows for a simpler usage of plugin functionality: instead of `require('mini.surround')` use `MiniSurround` (or manually `:lua MiniSurround.*` in command line); available from `v:lua` like `v:lua.MiniSurround`. Considering this, "module" and "Lua object" names can be used interchangeably: 'mini.surround' and 'MiniSurround' will mean the same thing.
+
+- Each supplied `config` table is stored in `config` field of global object. Like `MiniSurround.config`.
+
+- Values of `config` which affect runtime activity can be changed on the fly to have effect. For example, `MiniSurround.config.n_lines` can be changed during runtime; but changing `MiniSurround.config.mappings` won't have any effect (as mappings are created once during `setup()`).
+
+- If module works best with some specific non-default option value, it is set during `setup()`. If the value is not essential to module's functionality, it is done only if user or another plugin hasn't set it beforehand (no matter the value).
 
-- **Independence**. Modules are independent of each other and can be run without external dependencies. Although some of them may need dependencies for full experience.
+### Buffer local configuration
 
-- **Structure**. Each module is a submodule for a placeholder "mini" module. So, for example, "surround" module should be referred to as "mini.surround".  As later will be explained, this plugin can also be referred to as "MiniSurround".
+Each module can be additionally configured to use certain runtime config settings locally to buffer. See `mini.nvim-buffer-local-config` section in help file for more information.
 
-- **Setup**:
-    - Each module you want to use should be enabled separately with `require(<name of module>).setup({})`. Possibly replace `{}` with your config table or omit altogether to use defaults. You can supply only parts of config, the rest will be inferred from defaults.
+### Buffer names
 
-    - Call to module's `setup()` always creates a global Lua object with coherent camel-case name: `require('mini.surround').setup()` creates `_G.MiniSurround`. This allows for a simpler usage of plugin functionality: instead of `require('mini.surround')` use `MiniSurround` (or manually `:lua MiniSurround.*` in command line); available from `v:lua` like `v:lua.MiniSurround`. Considering this, "module" and "Lua object" names can be used interchangeably: 'mini.surround' and 'MiniSurround' will mean the same thing.
+All module-related buffers are named according to the following format: `mini<module-name>://<buffer-number>/<useful-info>` (forward slashes are used on any platform; `<useful-info>` may be empty). This structure allows creating identifiable, reasonably unique, and useful buffer names. For example, 'mini.files' buffers are created per displayed directory/file with names like `minifiles://10/path/to/displayed/directory`.
 
-    - Each supplied `config` table is stored in `config` field of global object. Like `MiniSurround.config`.
+### Disabling
 
-    - Values of `config` which affect runtime activity can be changed on the fly to have effect. For example, `MiniSurround.config.n_lines` can be changed during runtime; but changing `MiniSurround.config.mappings` won't have any effect (as mappings are created once during `setup()`).
+Each module's core functionality can be disabled globally or locally to buffer. See "Disabling" section in module's help page for more details. See `mini.nvim-disabling-recipes` section in main help file for common recipes.
 
-    - If module works best with some specific non-default option value, it is set during `setup()`. If the value is not essential to module's functionality, it is done only if user or another plugin hasn't set it beforehand (no matter the value).
+### Silencing
 
-- **Buffer local configuration**. Each module can be additionally configured to use certain runtime config settings locally to buffer. See `mini.nvim-buffer-local-config` section in help file for more information.
+Each module providing non-error feedback can be configured to not do that by setting `config.silent = true` (either inside `setup()` call or on the fly).
 
-- **Buffer names**. All module-related buffers are named according to the following format: `mini<module-name>://<buffer-number>/<useful-info>` (forward slashes are used on any platform; `<useful-info>` may be empty). This structure allows creating identifiable, reasonably unique, and useful buffer names. For example, 'mini.files' buffers are created per displayed directory/file with names like `minifiles://10/path/to/displayed/directory`.
+### Highlighting
 
-- **Disabling**. Each module's core functionality can be disabled globally or locally to buffer. See "Disabling" section in module's help page for more details. See `mini.nvim-disabling-recipes` section in main help file for common recipes.
+Appearance of module's output is controlled by certain set of highlight groups (see `:h highlight-groups`). By default they usually link to some semantically close built-in highlight group and are ensured to be defined after any color scheme takes effect. Use `:highlight` command or `vim.api.nvim_set_hl()` Lua function to customize highlighting. To see a more calibrated look, use 'mini.hues', 'mini.base16', or plugin's color scheme.
 
-- **Silencing**. Each module providing non-error feedback can be configured to not do that by setting `config.silent = true` (either inside `setup()` call or on the fly).
+### Stability
 
-- **Highlighting**. Appearance of module's output is controlled by certain set of highlight groups (see `:h highlight-groups`). By default they usually link to some semantically close built-in highlight group and are ensured to be defined after any color scheme takes effect. Use `:highlight` command or `vim.api.nvim_set_hl()` Lua function to customize highlighting. To see a more calibrated look, use 'mini.hues', 'mini.base16', or plugin's color scheme.
+Each module upon release is considered to be relatively stable: both in terms of setup and functionality. Any non-bugfix backward-incompatible change will be released gradually as much as possible.
 
-- **Stability**. Each module upon release is considered to be relatively stable: both in terms of setup and functionality. Any non-bugfix backward-incompatible change will be released gradually as much as possible.
+### Not filetype and language specific
 
-- **Not filetype/language specific**. Including functionality which needs several filetype/language specific implementations is an explicit no-goal of this project. This is mostly due to the potential increase in maintenance to keep implementation up to date. However, any part which might need filetype/language specific tuning should be designed to allow it by letting user set proper buffer options and/or local configuration.
+Including functionality which needs several filetype/language specific implementations is an explicit no-goal of this project. This is mostly due to the potential increase in maintenance to keep implementation up to date. However, any part which might need filetype/language specific tuning should be designed to allow it by letting user set proper buffer options and/or local configuration.
 
 ## Plugin color schemes