path: root/mnv/runtime/tutor/tutor2

===============================================================================
=    W e l c o m e   t o   t h e   M N V   T u t o r    -    Version 1.7      =
===============================================================================
=			    C H A P T E R   TWO				      =
===============================================================================

     Hic Sunt Dracones: if this is your first exposure to mnv and you
     intended to avail yourself of the introductory chapter, kindly type
     :q!<ENTER> and run mnvtutor for Chapter 1 instead.

     The approximate time required to complete this chapter is 8-10 minutes,
     depending upon how much time is spent with experimentation.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		     Lesson 2.1.1: MASTERING TEXT OBJECTS

   ** Operate on logical text blocks with precision using text objects **

  1. Practice word operations:
     - Place cursor on any word in the line below
     - Type  diw  to delete INNER word (word without surrounding space)
     - Type  daw  to delete A WORD (including trailing whitespace)
     - Try with other operators:  ciw  (change),  yiw  (yank),  gqiw  (format)

---> Practice on: "MNV's", (text_object), and 'powerful' words here.

  2. Work with bracketed content:
     - Put cursor inside any () {} [] <> pair below
     - Type  di(  or  dib  (delete inner bracket)
     - Type  da(  or  dab  (delete around brackets)
     - Try same with  i"/a"  for quotes,  it/at  for HTML/XML tags

---> Test cases: {curly}, [square], <angle>, and "quoted" items.

  3. Paragraph and sentence manipulation:
     - Use  dip  to delete inner paragraph (cursor anywhere in paragraph)
     - Use  vap  to visually select entire paragraph
     - Try  das  to delete a sentence (works between .!? punctuation)

  4. Advanced combinations:
     - ciwnew<ESC>    - Change current word to "new"
     - ciw"<CTRL-R>-"<ESC> - Wrap current word in quotes
     - gUit           - Uppercase inner HTML tag content
     - va"p           - Select quoted text and paste over it

---> Final exercise: (Modify "this" text) by [applying {various} operations]<

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		     Lesson 2.1.2: THE NAMED REGISTERS


         ** Store two yanked words concurrently and then paste them **

  1. Move the cursor to the line below marked --->

  2. Navigate to any point on the word 'Edward' and type   "ayiw

MNEMONIC: into register(") named (a) (y)ank (i)nner (w)ord

  3. Navigate forward to the word 'cookie' (fk or 3fc or $2b or /co<ENTER>)
     and type   "byiw

  4. Navigate to any point on the word 'Vince' and type   ciw<CTRL-R>a<ESC>

MNEMONIC: (c)hange (i)nner (w)ord with <contents of (r)egister> named (a)

  5. Navigate to any point on the word 'cake' and type   ciw<CTRL-R>b<ESC>

--->  a) Edward will henceforth be in charge of the cookie rations
      b) In this capacity, Vince will have sole cake discretionary powers

NOTE: Delete also works into registers, i.e. "sdiw will delete the word under
      the cursor into register s.

REFERENCE: 	Registers 	:h registers
		Named Registers :h quotea
		Motion 		:h motion.txt<ENTER> /inner<ENTER>
		CTRL-R		:h insert<ENTER> /CTRL-R<ENTER>

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		     Lesson 2.1.3: THE EXPRESSION REGISTER


	     ** Insert the results of calculations on the fly **

  1. Move the cursor to the line below marked --->

  2. Navigate to any point on the supplied number

  3. Type ciw<CTRL-R> followed by  =60*60*24<ENTER>

  4. On the next line, enter insert mode and add today's date with 
     <CTRL-R> followed by  =system('date')<ENTER>

NOTE: All calls to system are OS dependent, e.g. on Windows use 
      system('date /t')   or  :r!date /t

---> I have forgotten the exact number of seconds in a day, is it 84600?
     Today's date is: 

NOTE: the same can be achieved with :pu=system('date')
      or, with fewer keystrokes :r!date

REFERENCE: 	Expression Register 	:h quote=

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		     Lesson 2.1.4: THE NUMBERED REGISTERS


	** Press  yy and dd to witness their effect on the registers **

  1. Move the cursor to the line below marked --->

  2. Yank the zeroth line, then inspect registers with  :reg<ENTER>

  3. Delete line 0. with "cdd, then inspect registers
     (Where do you expect line 0 to be?)

  4. Continue deleting each successive line, inspecting :reg as you go

NOTE: You should notice that old full-line deletions move down the list
      as new full-line deletions are added

  5. Now (p)aste the following registers in order; c, 7, 4, 8, 2. i.e. "7p

---> 0. This
     9. wobble
     8. secret
     7. is
     6. on
     5. axis
     4. a
     3. war
     2. message
     1. tribute

NOTE: Whole line deletions (dd) are much longer lived in the numbered registers
      than whole line yanks, or deletions involving smaller movements

REFERENCE: 	Numbered Registers 	:h quote0

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		     Lesson 2.1.5: SPECIAL REGISTERS

 ** Use system clipboard and blackhole registers for advanced editing **

 Note: Clipboard use requires X11/Wayland libraries on Linux systems AND
       a MNV built with "+clipboard" (usually a Huge build). Check with
       ":version"  and ":echo has('clipboard_working')"

  1. Clipboard registers  +  and  *  :
     - "+y  - Yank to system clipboard (e.g. "+yy for current line)
     - "+p  - Paste from system clipboard
     - "* is primary selection on X11 (middle-click), "+ is clipboard

---> Try: "+yy then paste into another application with Ctrl-V or Cmd+V

  2. Blackhole register  _  discards text:
     - "_daw  - Delete word without saving to any register
     - Useful when you don't want to overwrite your default " register
     - Note this is using the "a Word" text object, introduced in a previous
       lession
     - "_dd   - Delete line without saving
     - "_dap  - Delete paragraph without saving
     - Combine with counts: 3"_dw

---> Practice: "_diw on any word to delete it without affecting yank history

  3. Combine with visual selections:
     - Select text with V then "+y
     - To paste from clipboard in insert mode: <CTRL-R>+
     - Try opening another application and paste from clipboard

  4. Remember:
     - Clipboard registers work across different MNV instances
     - Clipboard register is not always working
     - Blackhole prevents accidental register overwrites
     - Default " register is still available for normal yank/paste
     - Named registers (a-z) remain private to each MNV session

  5. Clipboard troubleshooting:
     - Check support with :echo has('clipboard_working')
     - 1 means available, 0 means not compiled in
     - On Linux, may need mnv-gtk or mnv-x11 package
       (check :version output)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		     Lesson 2.1.6: THE BEAUTY OF MARKS

	           ** Code monkey arithmetic avoidance **

NOTE: a common conundrum when coding is moving around large chunks of code.
      The following technique helps avoid number line calculations associated
      with operations like   "a147d   or   :945,1091d a   or even worse using
      i<CTRL-R> followed by   =1091-945<ENTER>   first

  1. Move the cursor to the line below marked --->

  2. Go to the first line of the function and mark it with   ma

NOTE: exact position on line is NOT important!

  3. Navigate to the end of the line and then the end of the code block 
     with   $%

  4. Delete the block into register a with   "ad'a

MNEMONIC: into register(") named (a) put the (d)eletion from the cursor to the
          LINE containing mark(') (a)

  5. Paste the block between BBB and CCC   "ap

NOTE: practice this operation multiple times to become fluent   ma$%"ad'a

---> AAA
     function itGotRealBigRealFast() {
       if ( somethingIsTrue ) {
         doIt()
       }
       // the taxonomy of our function has changed and it
       // no longer makes alphabetical sense in its current position

       // imagine hundreds of lines of code

       // naively you could navigate to the start and end and record or
       // remember each line number
     }
     BBB
     CCC

NOTE: marks and registers do not share a namespace, therefore register a is
      completely independent of mark a. This is not true of registers and
      macros.

REFERENCE: 	Marks 		:h marks
		Mark Motions 	:h mark-motions  (difference between ' and `)

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

		     Lesson 2.1 SUMMARY

  1. Text objects provide precision editing:
     - iw/aw - inner/around word
     - i[/a[ - inner/around bracket
     - i"/a" - inner/around quotes
     - it/at - inner/around tag
     - ip/ap - inner/around paragraph
     - is/as - inner/around sentence

  2. To store (yank, delete) text into, and retrieve (paste) from, a total of
     26 registers (a-z) 
  3. Yank a whole word from anywhere within a word:   yiw
  4. Change a whole word from anywhere within a word:   ciw
  5. Insert text directly from registers in insert mode:   <CTRL-R>a

  6. Insert the results of simple arithmetic operations: <CTRL-R> followed by
     =60*60<ENTER>
     in insert mode
  7. Insert the results of system calls: <CTRL-R> followed by
     =system('ls -1')<ENTER>
     in insert mode

  8. Inspect registers with   :reg
  9. Learn the final destination of whole line deletions: dd in the numbered
     registers, i.e. descending from register 1 - 9.  Appreciate that whole
     line deletions are preserved in the numbered registers longer than any
     other operation
 10. Learn the final destination of all yanks in the numbered registers and
     how ephemeral they are

 11. Place marks from command mode   m[a-zA-Z0-9]
 12. Move line-wise to a mark with   '

 13. Special registers:
     - "+/"*  - System clipboard (OS dependent)
     - "_     - Blackhole (discard deleted/yanked text)
     - "=     - Expression register
     - "-     - Small delete register

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  This concludes chapter two of the MNV Tutor. It is a work in progress.

  This chapter was written by Paul D. Parker and Christian Brabandt.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~