docs(ALL): tweak help files for better portability

Details:
- Rename 'mini.txt' into 'mini-nvim.txt', as MINI is a separate name.

- Make more friendly for the future "convert to markdown" script:
    - Don't use "#" prefix in inner "Title ~".
    - 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|). Otherwise links to neovim.io documentation won't
      work.

- 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.

Author: echasnovski

doc/mini-ai.txt

@@ -1,10 +1,9 @@
 *mini.ai* Extend and create a/i textobjects
-*MiniAi*
 
 MIT License Copyright (c) 2022 Evgeni Chasnovski
 
-==============================================================================
-
+------------------------------------------------------------------------------
+                                                                        *MiniAi*
 Enhance some builtin |text-objects| (like |a(|, |a)|, |a'|, and more),
 create new ones (like `a*`, `a<Space>`, `af`, `a?`, and more), and allow
 user to create their own.
@@ -61,7 +60,7 @@ What it doesn't (and probably won't) do:
   in 'targets.vim'). Whitespace handling is assumed to be done inside
   textobject specification (like `i(` and `i)` handle whitespace differently).
 
-# Setup ~
+Setup ~
 
 This module needs a setup with `require('mini.ai').setup({})` (replace
 `{}` with your `config` table). It will create global Lua table `MiniAi`
@@ -75,7 +74,7 @@ as `MiniAi.config`. See |mini.nvim-buffer-local-config| for more details.
 
 To stop module from showing non-error feedback, set `config.silent = true`.
 
-# Comparisons ~
+Comparisons ~
 
 - 'wellle/targets.vim':
     - Has limited support for creating own textobjects: it is constrained
@@ -104,7 +103,7 @@ To stop module from showing non-error feedback, set `config.silent = true`.
     - Doesn't support multiple search method (basically, only 'cover').
     - Doesn't support consecutive application of target textobject.
 
-# Disabling ~
+Disabling ~
 
 To disable, set `vim.g.miniai_disable` (globally) or `vim.b.miniai_disable`
 (for a buffer) to `true`. Considering high number of different scenarios
@@ -230,22 +229,22 @@ Notes:
   Examples:
     1. Either balanced `()` or balanced `[]` but both with inner edge space: >lua
 
-         -- Composed pattern
-         { { '%b()', '%b[]' }, '^. .* .$' }
+        -- Composed pattern
+        { { '%b()', '%b[]' }, '^. .* .$' }
 
-         -- Composed pattern expanded into equivalent array of nested patterns
-         { '%b()', '^. .* .$' } -- and
-         { '%b[]', '^. .* .$' }
+        -- Composed pattern expanded into equivalent array of nested patterns
+        { '%b()', '^. .* .$' } -- and
+        { '%b[]', '^. .* .$' }
 <
     2. Either "balanced `()` with inner edge space" or "balanced `[]` with
        no inner edge space", both with 5 or more characters: >lua
 
-         -- Composed pattern
-         { { { '%b()', '^. .* .$' }, { '%b[]', '^.[^ ].*[^ ].$' } }, '.....' }
+        -- Composed pattern
+        { { { '%b()', '^. .* .$' }, { '%b[]', '^.[^ ].*[^ ].$' } }, '.....' }
 
-         -- Composed pattern expanded into equivalent array of nested patterns
-         { '%b()', '^. .* .$', '.....' } -- and
-         { '%b[]', '^.[^ ].*[^ ].$', '.....' }
+        -- Composed pattern expanded into equivalent array of nested patterns
+        { '%b()', '^. .* .$', '.....' } -- and
+        { '%b[]', '^.[^ ].*[^ ].$', '.....' }
 <
 - SPAN MATCHES COMPOSED PATTERN if it matches at least one nested pattern
   from expanded composed pattern.
@@ -461,9 +460,7 @@ Default values:
     silent = false,
   }
 <
-# Options ~
-
-## Custom textobjects ~
+Custom textobjects ~
 
 User can define own textobjects by supplying `config.custom_textobjects`.
 It should be a table with keys being single character textobject identifier
@@ -514,7 +511,7 @@ Examples:
 <
 There are more example specifications in |MiniAi-textobject-specification|.
 
-## Search method ~
+Search method ~
 
 Value of `config.search_method` defines how best match search is done.
 Based on its value, one of the following matches will be selected:
@@ -555,7 +552,7 @@ Here is an example of what `a)` textobject is based on a value of
 - `'prev'`: `(a) bbb (c)` -> `(a)`. Same outcome for `(bbb)`.
 - `'nearest'`: depends on cursor position (same as in `'cover_or_nearest'`).
 
-## Mappings ~
+Mappings ~
 
 Mappings `around_next` / `inside_next` and `around_last` / `inside_last` are
 essentially `around` / `inside` but using search method `'next'` and `'prev'`.
@@ -636,7 +633,7 @@ Example: >lua
       ['|'] = gen_spec.pair('|', '|', { type = 'non-balanced' }),
     }
   })
-
+<
 ------------------------------------------------------------------------------
                                                     *MiniAi.gen_spec.argument()*
                        `MiniAi.gen_spec.argument`({opts})
@@ -685,7 +682,7 @@ Example:
   only alphanumeric or underscore (not dot).
 
 Parameters ~
-{opts} `(table|nil)` Optsion. Allowed fields:
+{opts} `(table|nil)` Options. Allowed fields:
   - <name_pattern> - string pattern of character set allowed in function name.
     Default: `'[%w_%.]'` (alphanumeric, underscore, or dot).
     Note: should be enclosed in `[]`.
@@ -793,10 +790,10 @@ Return ~
   corresponding (`a` or `i`) treesitter capture.
 
 See also ~
-|MiniAi-textobject-specification| for how this type of textobject
+- |MiniAi-textobject-specification| for how this type of textobject
   specification is processed.
-|vim.treesitter.get_query()| for how query is fetched.
-|Query:iter_captures()| for how all query captures are iterated in case of
+- |vim.treesitter.get_query()| for how query is fetched.
+- |Query:iter_captures()| for how all query captures are iterated in case of
   no 'nvim-treesitter'.
 
 ------------------------------------------------------------------------------

doc/mini-align.txt

@@ -1,10 +1,9 @@
 *mini.align* Align text interactively
-*MiniAlign*
 
 MIT License Copyright (c) 2022 Evgeni Chasnovski
 
-==============================================================================
-
+------------------------------------------------------------------------------
+                                                                     *MiniAlign*
 Rich and flexible customization of both alignment rules and user interaction.
 Works with charwise, linewise, and blockwise selections in both Normal mode
 (on textobject/motion; with dot-repeat) and Visual mode.
@@ -40,7 +39,7 @@ Features:
 - Every user interaction is accompanied with helper status message showing
   relevant information about current alignment process.
 
-# Setup ~
+Setup ~
 
 This module needs a setup with `require('mini.align').setup({})` (replace
 `{}` with your `config` table). It will create global Lua table `MiniAlign`
@@ -54,7 +53,7 @@ as `MiniAlign.config`. See |mini.nvim-buffer-local-config| for more details.
 
 To stop module from showing non-error feedback, set `config.silent = true`.
 
-# Comparisons ~
+Comparisons ~
 
 - 'junegunn/vim-easy-align':
     - 'mini.align' is mostly designed after 'junegunn/vim-easy-align', so
@@ -86,7 +85,7 @@ To stop module from showing non-error feedback, set `config.silent = true`.
       desirable. 'mini.align' does not by design: use Visual selection or
       textobject/motion to explicitly define region to align.
 
-# Disabling ~
+Disabling ~
 
 To disable, set `vim.g.minialign_disable` (globally) or `vim.b.minialign_disable`
 (for a buffer) to `true`. Considering high number of different scenarios
@@ -366,7 +365,7 @@ Special configurations for common splits ~
     After typing `<Space>`: >
       a  b  c
       aa bb cc
-
+<
 ------------------------------------------------------------------------------
                                                             *MiniAlign-examples*
 More complex examples to explore functionality
@@ -493,9 +492,7 @@ Default values:
     silent = false,
   }
 <
-# Options ~
-
-## Modifiers ~
+Modifiers ~
 
 `MiniAlign.config.modifiers` is used to define interactive user experience
 of managing alignment process. It is a table with single character keys and
@@ -537,7 +534,7 @@ Examples:
     },
   })
 <
-## Options ~
+Options ~
 
 `MiniAlign.config.options` defines default values of options used to control
 behavior of steps.
@@ -548,7 +545,7 @@ Examples:
 For more details about options see |MiniAlign.align_strings()| and entries of
 |MiniAlign.gen_step| for default main steps.
 
-## Steps ~
+Steps ~
 
 `MiniAlign.config.steps` defines default steps to be applied during
 alignment process.

doc/mini-animate.txt

@@ -1,10 +1,9 @@
 *mini.animate* Animate common Neovim actions
-*MiniAnimate*
 
 MIT License Copyright (c) 2022 Evgeni Chasnovski
 
-==============================================================================
-
+------------------------------------------------------------------------------
+                                                                   *MiniAnimate*
 Features:
 - Works out of the box with a single `require('mini.animate').setup()`.
   No extra mappings or commands needed.
@@ -42,7 +41,7 @@ Notes:
   mappings, etc.). See |MiniAnimate.config.scroll| and
   |MiniAnimate.config.resize| for more details.
 
-# Setup ~
+Setup ~
 
 This module needs a setup with `require('mini.animate').setup({})` (replace
 `{}` with your `config` table). It will create global Lua table `MiniAnimate`
@@ -54,7 +53,7 @@ You can override runtime config settings (like `config.modifiers`) locally
 to buffer inside `vim.b.minianimate_config` which should have same structure
 as `MiniAnimate.config`. See |mini.nvim-buffer-local-config| for more details.
 
-# Comparisons ~
+Comparisons ~
 
 - Neovide:
     - Neovide is a standalone GUI which has more control over its animations.
@@ -79,15 +78,15 @@ as `MiniAnimate.config`. See |mini.nvim-buffer-local-config| for more details.
       while 'mini.animate' animates any resize with appropriate values of
       'winheight' / 'winwidth' and 'winminheight' / 'winminwidth').
 
-# Highlight groups ~
+Highlight groups ~
 
 * `MiniAnimateCursor` - highlight of cursor during its animated movement.
 * `MiniAnimateNormalFloat` - highlight of floating window for `open` and
   `close` animations.
 
 To change any highlight group, modify it directly with |:highlight|.
 
-# Disabling ~
+Disabling ~
 
 To disable, set `vim.g.minianimate_disable` (globally) or
 `vim.b.minianimate_disable` (for a buffer) to `true`. Considering high
@@ -184,7 +183,7 @@ Default values:
     },
   }
 <
-# General ~
+General ~
                                                             *MiniAnimate-timing*
 - Every animation is a non-blockingly scheduled series of specific actions.
   They are executed in a sequence of timed steps controlled by `timing` option.
@@ -208,7 +207,7 @@ Default values:
   animation steps. Outputs `nil` and empty table result in no animation.
 
                                                      *MiniAnimate.config.cursor*
-# Cursor ~
+Cursor ~
 
 This animation is triggered for each movement of cursor inside same window
 and buffer. Its visualization step consists from placing single extmark (see
@@ -251,7 +250,7 @@ Configuration example: >lua
 After animation is done, `MiniAnimateDoneCursor` event is triggered.
 
                                                      *MiniAnimate.config.scroll*
-# Scroll ~
+Scroll ~
 
 This animation is triggered for each vertical scroll of current window.
 Its visualization step consists from performing a small subscroll which all
@@ -311,7 +310,7 @@ Configuration example: >lua
 After animation is done, `MiniAnimateDoneScroll` event is triggered.
 
                                                      *MiniAnimate.config.resize*
-# Resize ~
+Resize ~
 
 This animation is triggered for window resize while having same layout of
 same windows. For example, it won't trigger when window is opened/closed or
@@ -369,8 +368,9 @@ Configuration example: >lua
 <
 After animation is done, `MiniAnimateDoneResize` event is triggered.
 
-                              *MiniAnimate.config.open* *MiniAnimate.config.close*
-# Window open/close ~
+                                                       *MiniAnimate.config.open*
+                                                      *MiniAnimate.config.close*
+Window open/close ~
 
 These animations are similarly triggered for regular (non-floating) window
 open/close. Their visualization step consists from drawing empty floating

doc/mini-base16.txt

@@ -1,10 +1,9 @@
 *mini.base16* Base16 colorscheme creation
-*MiniBase16*
 
 MIT License Copyright (c) 2021 Evgeni Chasnovski
 
-==============================================================================
-
+------------------------------------------------------------------------------
+                                                                    *MiniBase16*
 Fast implementation of 'chriskempson/base16' color scheme (with Copyright
 (C) 2012 Chris Kempson) adapted for modern Neovim Lua plugins.
 Extra features:
@@ -55,7 +54,7 @@ Supported highlight groups:
     - 'stevearc/aerial.nvim'
     - 'williamboman/mason.nvim'
 
-# Setup ~
+Setup ~
 
 This module needs a setup with `require('mini.base16').setup({})` (replace
 `{}` with your `config` table). It will create global Lua table
@@ -95,7 +94,7 @@ Example: >lua
     },
   })
 <
-# Notes ~
+Notes ~
 
 1. This is used to create some of plugin's color schemes
    (see |MiniBase16-color-schemes|).
@@ -119,8 +118,6 @@ a |MiniBase16| theme created with faster version of the following Lua code: >lua
 Activate them as regular |colorscheme| (for example, `:colorscheme minischeme`).
 
                                                                     *minischeme*
-## minischeme ~
-
 Blue and yellow main colors with high contrast and saturation palette.
 Palettes are: >lua
 
@@ -131,8 +128,6 @@ Palettes are: >lua
   MiniBase16.mini_palette('#e2e5ca', '#002a83', 75)
 <
                                                                       *minicyan*
-## minicyan ~
-
 Cyan and grey main colors with moderate contrast and saturation palette.
 Palettes are: >lua
 
@@ -191,9 +186,7 @@ Default values:
     plugins = { default = true },
   }
 <
-# Options ~
-
-## Plugin integrations ~
+Plugin integrations ~
 
 `config.plugins` defines for which supported plugins highlight groups will
 be created. Limiting number of integrations slightly decreases startup time.
@@ -220,7 +213,7 @@ Create base16 palette based on the HEX (string '#RRGGBB') colors of main
 background and foreground with optional setting of accent chroma (see
 details).
 
-# Algorithm design ~
+Algorithm design ~
 
 - Main operating color space is
   [CIELCh(uv)](https://en.wikipedia.org/wiki/CIELUV#Cylindrical_representation_(CIELCh))