-------------------------------------------------------------------------------
Hints and tipes for vim.
-------------------------------------------------------------------------------
General

Note sections starting with " are vimrc comments designed so it can be
included verbatum into your .vimrc file.

For a great source of vim tips and scripts see..
   http://vim.sourceforge.net/tip_search.php

Great tips..

  Vim Tips Wiki
     https://vim.fandom.com/wiki/Vim_Tips_Wiki

Use vim to read manpages (with ctrl-[ and ctrl-t references)
  http://www.pixelbeat.org/settings/.bashrc

  export MANPAGER='bash -c "vim -MRn \
                     -c \"set ft=man nomod nolist nospell nonu\" \
                     -c \"nm q :qa!<CR>\" -c \"nm <end> G\" \
                     -c \"nm <home> gg\"</dev/tty <(col -b)"'

-------------------------------------------------------------------------------
File Specific Settings...

One  of the  things about  vim that  are both  quite simple  yet very useful
is that you can store  by-file settings...

the syntax is as follows:
    // vim:set ts=4 sw=4 nowrap:
    /* vim:noai:ts=2:sw=4: */
    # vim:filetype=sh :


For more info see  :help modline
They must be in the first or last 5 lines (by default) of the file.

-------------------------------------------------------------------------------
Enable Syntax Highlighting...

"
" Mininal .vimrc to enable color syntax highlighting
"
"
" General options
"
version 4.0             " avoid warning for wrong version
set nocompatible        " Use Vim defaults like multi-undo (much better!)
set noedcompatible      " turn off wierd :s///g behaviour (g always means g)
"
" Adding Syntax Highlighing
"
"set background=dark    " use light colors for a dark background (def: light)
syntax on               " turn on syntax checking (after background is set)

" no-bold for color terminal comments
hi Comment   cterm=NONE

" default non-text (formating) characters (default bold blue)
"hi NonText   term=bold  cterm=bold   ctermfg=0   " bold black --> IE: grey

-------------------------------------------------------------------------------
"
" List Mode Highlighting
"
" Setup a un-intrusive list mode and a toggle function between the list
" mode and a cut and paste mode so I can cut text without the special
" list mode formatting geting in the way.
"
"   <F2>   toggle between the two modes.
"
" The following are interesting characters that you can use for list mode.
" alturnatives:  ¶ ¥ § ± × ¤ « » ¸   ¬ ÷ ­ ¯ ¨ ´ £ ¿ ¡ ¢ © © º ° ¹ ² ³ ¼ ½ ¾

" Set the mode depending on status of paste
function SetPasteListMode()
  if &paste " is paste mode already on?
    set showbreak=
  else
    " chars to use in `list'  mode
    set showbreak=±
    set listchars=tab:» ,trail:­,extends:±
    "
    " alturnative list chars
    "set showbreak=
    "set listchars=tab:» ,trail:­,extends:±,eol:§
    "
  endif
endfunction

" Toggle between paste mode and list mode
function TogglePasteList()
  if &paste  " is paste mode on?
    echo "paste mode OFF"
    set nopaste list
  else
    echo "paste mode ON"
    set paste nolist
  endif
  let @_=SetPasteListMode()
endfunction

" Set the key mappings to toggle
map  <F2> :let @_=TogglePasteList()<CR>
map  QP   :let @_=TogglePasteList()<CR>
imap <F2> :let @_=TogglePasteList()<CR>a
" note the last above will go into paste mode but will not leave it as <F2>
" will be pasted instead of the action being performed.  The following will
" re-activate this.  However it will not re-activate list mode :-(
set pastetoggle=<F2>    " this will toggle the paste mode while in paste mode!

-------------------------------------------------------------------------------
Visual Block hints and tips

To replace a visual block (^V) with the same string on every line
use substitute. (s)
   EG:  ^V  {cursour moves} s  string ESC

To replace blocked region with a specific character (EG: space)
use replace (r)
   EG:  ^V  {cursour moves} r character

Insert (I) will insert before the blocked text, and Append (A) after it.
Uppercase (U) will make character uppercase. ditto for lowercase (u).
Shift (>) works too.

In all cases the original block is still in the yank buffer

QUESTION:  How do you paste-overwrite (replace)  instead of paste insert?

-------------------------------------------------------------------------------
Edit Directories (Explorer)

Vim File Explorer
     vim {directory}
or   :e {directory}
In this mode return will open a file, R rename

-------------------------------------------------------------------------------
Edit Remove file (Netrw)

  vim scp://hostname/path/to/file

directory explore
  vim scp://hostname/path/to/file


-------------------------------------------------------------------------------
Convert to HTML

To convert the current systax highlighted file to HTML for web or printing
use...
    :so $VIMRUNTIME/syntax/2html.vim
then save the ".html" file

-------------------------------------------------------------------------------
Paste in Command (Normal) Mode...  (from Vim-8.0)

Normally if you do a mouse paste, Vim will automatically drop into
'paste' mode so as to insert pre-formated text that is being pasted in.
It does this by asking the "xterm" to wrapper pasted text with special ANSI
control sequences..

Details are in...
  https://cirw.in/blog/bracketed-paste

" Just disable 'xterm-bracket-paste' completely
"set t_BE=
"
" Alternative... prevent the <PasteStart> character sequence from
" activating insert-paste-mode when in normal or command-mode.
" But still allow mouse pasting to activate paste mode temporarilly
" preventing vim auto-indenting pasted text.
nmap <PasteStart> <NOP>
nmap <PasteEnd>   <NOP>
cmap <PasteStart> <NOP>
cmap <PasteEnd>   <NOP>

I added that soltuion to my previous enquiry
  https://unix.stackexchange.com/questions/364047

Additioning information...
  Docs on mapping fast escape codes in vim
    http://vim.wikia.com/wiki/Mapping_fast_keycodes_in_terminal_Vim

-------------------------------------------------------------------------------
Password Input for File Decryption Failing (fixed)

Seems Vim is putting XTerms into a special mode 'modifyOtherKeys', that allows
them to reconise shifted, escaped, meta and control keys more easilly.  However
in "autocmd" that ask for input from the user this causes keys like 'A'
(shifted-A) to return an ANSI control sequence...

For example start vim with a file nameed "file.test" (does not need to exist),
then type...

:" check t_TI is set to t_TI=^[[>4;2m
:set t_TI
:" Set an autocommand to read from TTY
:autocmd  BufWritePre,FileWritePre   *.test !bash -c 'cat </dev/tty >/dev/tty'
:" now write the file to run the above autocmd
:w

Typing 'A' then returns the ANSI sequence   \e[27;2;65~
That is a 'A' key ascii '65', that has been shifted '2'.
Instead of just a 'A' as a capital letter 'A' as normal.

NOTE: you can not even type Ctrl-D to break the above input, and will need
to use another terminal to kill the 'cat' process.


This means you cannot type 'A' as a password for file de/encryption.
using "GPG", "openssl enc", etc...

After much searching I found...
  https://invisible-island.net/xterm/ctlseqs/ctlseqs.pdf
Defined on Page 19, and talked about on page 30.

The mode is being set by the vim internal termcap entries...
    t_TI   \e[>4;2m             put terminal into "raw" mode
    t_TE   \e[>4m               end of 'raw' mode
The 4 is 'modifyOtherKeys' which is the problem,  2 is 'FunctionKeys'.

You can see all the current termcap entries using    :set termcap


VIM GitHUB patch 8.1.2134 causes the issue...
  https://github.com/vim/vim/issues/4974#issuecomment-541431801

Solutions...
* Disable the use of modifyOtherKeys completely using this in ".vimrc"

    if (v:version >= 820)
      let &t_TI = "<Csi>>2m"
      let &t_TE = ""
    endif

* I can now use echoraw() to wrapper the filter function call within the
  autocommand.

    call echoraw(&t_TE)
    "... do the terminal input filter
    call echoraw(&t_TI)

* In the input filter program disable the 'xterm modifyOtherKeys' mode.

    case "$TERM" in
    xterm*) echo -n $'\e[>4n' >/dev/tty ;;
    esac

  WARNING: For a period xterms would also gobble the next character that
  followed that sequence, so adding a extra character like '~' to the string
  afetr the escape sequence was needed.  That seems to have now been fixed.

My report of the problem, and solution
  https://github.com/vim/vim/issues/5617
In respose the "echoraw()" function was added.
Which I do not regard as a proper soltuion.

Other reports involving the problem...
  https://github.com/vim/vim/issues/5612
  https://github.com/vim/vim/issues/5200
  https://github.com/vim/vim/issues/2737

Seems to be all fixed now.

===============================================================================
Syntax Highlighting


The syntax manual
  :help syntax

Also see on adding to or replacing a syntax configuration for a filetype
  :help new-filetype

For a summery of the Syntax names, and what they look like....
   :help group-name

     Syntax______Color____
     Comment     cyan
     Identifier  bold cyan
     PreProc     light blue
     Constant    magenta

     Statement   yellow
     Type        green
     Special     red

     Underlined  underlined_cyan   (hyperlink)
     Ignore      grey              (uninportant item)
     Error       invert red        (erronious construct)
     ToDo        invert yellow     (TODO FIXME XXX)


===============================================================================
Macro tricks...

---
Incrementing a number

  Replacate a line "(1,1)" incrementing the second number.

  qqYpW<c-a>q135@q

     qq     starts a macro recording
     Y      yanks the line
     p      paste into next line
     W      just to the second number (position)
     <c-a>  increment the number  (also takes into accout negatives)
     q      end macro record
     135@q  repeat macro 135 times!

Vim v7 on can do this in a visual block
BUT it does not increment a list of numbers

    block select on the number
    g<c-a>

You could also use  VisIncr plugin
This will increment a list of numbers but is a very old package

    use a block select on the number
    type :II

-------------------------------------------------------------------------------
Edit all files with a specific word

Use the builtin VIM grep

  :grep word file-list...

This will look through all the files in file-list and edit them
the cursour will be position at the start of the first 'word' found in the
file.

-------------------------------------------------------------------------------