path: root/data/vim/patches/8.1.1069

To: vim_dev@googlegroups.com
Subject: Patch 8.1.1069
Fcc: outbox
From: Bram Moolenaar <Bram@moolenaar.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
------------

Patch 8.1.1069
Problem:    Source README file doesn't look nice on github.
Solution:   Turn it into markdown, still readable as plain text.
            (WenxuanHuang, closes #4141)
Files:	    src/README.txt, src/README.md, Filelist


*** ../vim-8.1.1068/src/README.txt	2019-02-13 22:45:21.508636195 +0100
--- src/README.txt	1970-01-01 01:00:00.000000000 +0100
***************
*** 1,162 ****
- README for the Vim source code
- 
- Here are a few hints for finding your way around the source code.  This
- doesn't make it less complex than it is, but it gets you started.
- 
- You might also want to read ":help development".
- 
- 
- JUMPING AROUND
- 
- First of all, use ":make tags" to generate a tags file, so that you can jump
- around in the source code.
- 
- To jump to a function or variable definition, move the cursor on the name and
- use the CTRL-] command.  Use CTRL-T or CTRL-O to jump back.
- 
- To jump to a file, move the cursor on its name and use the "gf" command.
- 
- Most code can be found in a file with an obvious name (incomplete list):
- 	autocmd.c	autocommands
- 	buffer.c	manipulating buffers (loaded files)
- 	diff.c		diff mode (vimdiff)
- 	eval.c		expression evaluation
- 	fileio.c	reading and writing files
- 	findfile.c	search for files in 'path'
- 	fold.c		folding
- 	getchar.c	getting characters and key mapping
- 	indent.c	C and Lisp indentation
- 	mark.c		marks
- 	mbyte.c		multi-byte character handling
- 	memfile.c	storing lines for buffers in a swapfile
- 	memline.c	storing lines for buffers in memory
- 	menu.c		menus
- 	message.c	(error) messages
- 	ops.c		handling operators ("d", "y", "p")
- 	option.c	options
- 	quickfix.c	quickfix commands (":make", ":cn")
- 	regexp.c	pattern matching
- 	screen.c	updating the windows
- 	search.c	pattern searching
- 	sign.c		signs
- 	spell.c		spell checking
- 	syntax.c	syntax and other highlighting
- 	tag.c		tags
- 	term.c		terminal handling, termcap codes
- 	undo.c		undo and redo
- 	window.c	handling split windows
- 
- 
- DEBUGGING
- 
- If you have a reasonable recent version of gdb, you can use the :Termdebug
- command to debug Vim.  See  ":help :Termdebug".
- 
- When something is time critical or stepping through code is a hassle, use the
- channel logging to create a time-stamped log file.  Add lines to the code like
- this:
- 	ch_log(NULL, "Value is now %02x", value);
- After compiling and starting Vim, do:
- 	:call ch_logfile('debuglog', 'w')
- And edit "debuglog" to see what happens.  The channel functions already have
- ch_log() calls, thus you always see that in the log.
- 
- 
- IMPORTANT VARIABLES
- 
- The current mode is stored in "State".  The values it can have are NORMAL,
- INSERT, CMDLINE, and a few others.
- 
- The current window is "curwin".  The current buffer is "curbuf".  These point
- to structures with the cursor position in the window, option values, the file
- name, etc.  These are defined in structs.h.
- 
- All the global variables are declared in globals.h.
- 
- 
- THE MAIN LOOP
- 
- This is conveniently called main_loop().  It updates a few things and then
- calls normal_cmd() to process a command.  This returns when the command is
- finished.
- 
- The basic idea is that Vim waits for the user to type a character and
- processes it until another character is needed.  Thus there are several places
- where Vim waits for a character to be typed.  The vgetc() function is used for
- this.  It also handles mapping.
- 
- Updating the screen is mostly postponed until a command or a sequence of
- commands has finished.  The work is done by update_screen(), which calls
- win_update() for every window, which calls win_line() for every line.
- See the start of screen.c for more explanations.
- 
- 
- COMMAND-LINE MODE
- 
- When typing a ":", normal_cmd() will call getcmdline() to obtain a line with
- an Ex command.  getcmdline() contains a loop that will handle each typed
- character.  It returns when hitting <CR> or <Esc> or some other character that
- ends the command line mode.
- 
- 
- EX COMMANDS
- 
- Ex commands are handled by the function do_cmdline().  It does the generic
- parsing of the ":" command line and calls do_one_cmd() for each separate
- command.  It also takes care of while loops.
- 
- do_one_cmd() parses the range and generic arguments and puts them in the
- exarg_t and passes it to the function that handles the command.
- 
- The ":" commands are listed in ex_cmds.h.  The third entry of each item is the
- name of the function that handles the command.  The last entry are the flags
- that are used for the command.
- 
- 
- NORMAL MODE COMMANDS
- 
- The Normal mode commands are handled by the normal_cmd() function.  It also
- handles the optional count and an extra character for some commands.  These
- are passed in a cmdarg_t to the function that handles the command.
- 
- There is a table nv_cmds in normal.c which lists the first character of every
- command.  The second entry of each item is the name of the function that
- handles the command.
- 
- 
- INSERT MODE COMMANDS
- 
- When doing an "i" or "a" command, normal_cmd() will call the edit() function.
- It contains a loop that waits for the next character and handles it.  It
- returns when leaving Insert mode.
- 
- 
- OPTIONS
- 
- There is a list with all option names in option.c, called options[].
- 
- 
- THE GUI
- 
- Most of the GUI code is implemented like it was a clever terminal.  Typing a
- character, moving a scrollbar, clicking the mouse, etc. are all translated
- into events which are written in the input buffer.  These are read by the
- main code, just like reading from a terminal.  The code for this is scattered
- through gui.c.  For example: gui_send_mouse_event() for a mouse click and
- gui_menu_cb() for a menu action.  Key hits are handled by the system-specific
- GUI code, which calls add_to_input_buf() to send the key code.
- 
- Updating the GUI window is done by writing codes in the output buffer, just
- like writing to a terminal.  When the buffer gets full or is flushed,
- gui_write() will parse the codes and draw the appropriate items.  Finally the
- system-specific GUI code will be called to do the work.
- 
- 
- DEBUGGING THE GUI
- 
- Remember to prevent that gvim forks and the debugger thinks Vim has exited,
- add the "-f" argument.  In gdb: "run -f -g".
- 
- When stepping through display updating code, the focus event is triggered
- when going from the debugger to Vim and back.  To avoid this, recompile with
- some code in gui_focus_change() disabled.
--- 0 ----
*** ../vim-8.1.1068/src/README.md	2019-03-29 13:09:27.404892258 +0100
--- src/README.md	2019-03-29 13:03:37.460960186 +0100
***************
*** 0 ****
--- 1,190 ----
+ ![Vim Logo](https://github.com/vim/vim/blob/master/runtime/vimlogo.gif)
+ 
+ # Vim source code #
+ 
+ Here are a few hints for finding your way around the source code.  This
+ doesn't make it less complex than it is, but it gets you started.
+ 
+ You might also want to read
+ [`:help development`](http://vimdoc.sourceforge.net/htmldoc/develop.html#development).
+ 
+ 
+ ## Jumping around ##
+ 
+ First of all, use `:make tags` to generate a tags file, so that you can jump
+ around in the source code.
+ 
+ To jump to a function or variable definition, move the cursor on the name and
+ use the `CTRL-]` command.  Use `CTRL-T` or `CTRL-O` to jump back.
+ 
+ To jump to a file, move the cursor on its name and use the `gf` command.
+ 
+ Most code can be found in a file with an obvious name (incomplete list):
+ 
+ File name | Description
+ --------- | -----------
+ autocmd.c	| autocommands
+ buffer.c	| manipulating buffers (loaded files)
+ diff.c		| diff mode (vimdiff)
+ eval.c		| expression evaluation
+ fileio.c	| reading and writing files
+ findfile.c	| search for files in 'path'
+ fold.c		| folding
+ getchar.c	| getting characters and key mapping
+ indent.c	| C and Lisp indentation
+ mark.c		| marks
+ mbyte.c		| multi-byte character handling
+ memfile.c	| storing lines for buffers in a swapfile
+ memline.c	| storing lines for buffers in memory
+ menu.c		| menus
+ message.c	| (error) messages
+ ops.c		  | handling operators ("d", "y", "p")
+ option.c	| options
+ quickfix.c	| quickfix commands (":make", ":cn")
+ regexp.c	| pattern matching
+ screen.c	| updating the windows
+ search.c	| pattern searching
+ sign.c		| signs
+ spell.c		| spell checking
+ syntax.c	|  syntax and other highlighting
+ tag.c		  | tags
+ term.c		| terminal handling, termcap codes
+ undo.c		| undo and redo
+ window.c	| handling split windows
+ 
+ 
+ ## Debugging ##
+ 
+ If you have a reasonable recent version of gdb, you can use the `:Termdebug`
+ command to debug Vim.  See  `:help :Termdebug`.
+ 
+ When something is time critical or stepping through code is a hassle, use the
+ channel logging to create a time-stamped log file.  Add lines to the code like
+ this:
+ 
+ 	ch_log(NULL, "Value is now %02x", value);
+ 
+ After compiling and starting Vim, do:
+ 
+ 	:call ch_logfile('debuglog', 'w')
+ 
+ And edit `debuglog` to see what happens.  The channel functions already have
+ `ch_log()` calls, thus you always see that in the log.
+ 
+ 
+ ## Important Variables ##
+ 
+ The current mode is stored in `State`.  The values it can have are `NORMAL`,
+ `INSERT`, `CMDLINE`, and a few others.
+ 
+ The current window is `curwin`.  The current buffer is `curbuf`.  These point
+ to structures with the cursor position in the window, option values, the file
+ name, etc.  These are defined in
+ [`structs.h`](https://github.com/vim/vim/blob/master/src/globals.h).
+ 
+ All the global variables are declared in
+ [`globals.h`](https://github.com/vim/vim/blob/master/src/structs.h).
+ 
+ 
+ ## The main loop ##
+ 
+ This is conveniently called `main_loop()`.  It updates a few things and then
+ calls `normal_cmd()` to process a command.  This returns when the command is
+ finished.
+ 
+ The basic idea is that Vim waits for the user to type a character and
+ processes it until another character is needed.  Thus there are several places
+ where Vim waits for a character to be typed.  The `vgetc()` function is used
+ for this.  It also handles mapping.
+ 
+ Updating the screen is mostly postponed until a command or a sequence of
+ commands has finished.  The work is done by `update_screen()`, which calls
+ `win_update()` for every window, which calls `win_line()` for every line.
+ See the start of
+ [`screen.c`](https://github.com/vim/vim/blob/master/src/screen.c)
+ for more explanations.
+ 
+ 
+ ## Command-line mode ##
+ 
+ When typing a `:`, `normal_cmd()` will call `getcmdline()` to obtain a line
+ with an Ex command.  `getcmdline()` contains a loop that will handle each typed
+ character.  It returns when hitting `CR` or `Esc` or some other character that
+ ends the command line mode.
+ 
+ 
+ ## Ex commands ##
+ 
+ Ex commands are handled by the function `do_cmdline()`.  It does the generic
+ parsing of the `:` command line and calls `do_one_cmd()` for each separate
+ command.  It also takes care of while loops.
+ 
+ `do_one_cmd()` parses the range and generic arguments and puts them in the
+ `exarg_t` and passes it to the function that handles the command.
+ 
+ The `:` commands are listed in `ex_cmds.h`.  The third entry of each item is
+ the name of the function that handles the command.  The last entry are the
+ flags that are used for the command.
+ 
+ 
+ ## Normal mode commands ##
+ 
+ The Normal mode commands are handled by the `normal_cmd()` function.  It also
+ handles the optional count and an extra character for some commands.  These
+ are passed in a `cmdarg_t` to the function that handles the command.
+ 
+ There is a table `nv_cmds` in
+ [`normal.c`](https://github.com/vim/vim/blob/master/src/normal.c)
+ which lists the first character of every command.  The second entry of each
+ item is the name of the function that handles the command.
+ 
+ 
+ ## Insert mode commands ##
+ 
+ When doing an `i` or `a` command, `normal_cmd()` will call the `edit()`
+ function. It contains a loop that waits for the next character and handles it.
+ It returns when leaving Insert mode.
+ 
+ 
+ ## Options ##
+ 
+ There is a list with all option names in
+ [`option.c`](https://github.com/vim/vim/blob/master/src/option.c),
+ called `options[]`.
+ 
+ 
+ ## The GUI ##
+ 
+ Most of the GUI code is implemented like it was a clever terminal.  Typing a
+ character, moving a scrollbar, clicking the mouse, etc. are all translated
+ into events which are written in the input buffer.  These are read by the
+ main code, just like reading from a terminal.  The code for this is scattered
+ through [`gui.c`](https://github.com/vim/vim/blob/master/src/gui.c).
+ For example, `gui_send_mouse_event()` for a mouse click and `gui_menu_cb()` for
+ a menu action.  Key hits are handled by the system-specific GUI code, which
+ calls `add_to_input_buf()` to send the key code.
+ 
+ Updating the GUI window is done by writing codes in the output buffer, just
+ like writing to a terminal.  When the buffer gets full or is flushed,
+ `gui_write()` will parse the codes and draw the appropriate items.  Finally the
+ system-specific GUI code will be called to do the work.
+ 
+ 
+ ## Debugging the GUI ##
+ 
+ Remember to prevent that gvim forks and the debugger thinks Vim has exited,
+ add the `-f` argument.  In gdb: `run -f -g`.
+ 
+ When stepping through display updating code, the focus event is triggered
+ when going from the debugger to Vim and back.  To avoid this, recompile with
+ some code in `gui_focus_change()` disabled.
+ 
+ 
+ ## Contributing ##
+ 
+ If you would like to help making Vim better, see the
+ [`CONTRIBUTING.md`](https://github.com/vim/vim/blob/master/CONTRIBUTING.md)
+ file.
+ 
+ 
+ This is `README.md` for version 8.1 of the Vim source code.
*** ../vim-8.1.1068/Filelist	2019-03-22 16:33:03.483016118 +0100
--- Filelist	2019-03-29 13:09:00.533173252 +0100
***************
*** 9,15 ****
  		appveyor.yml \
  		ci/appveyor.bat \
  		src/Make_all.mak \
! 		src/README.txt \
  		src/alloc.h \
  		src/arabic.c \
  		src/ascii.h \
--- 9,15 ----
  		appveyor.yml \
  		ci/appveyor.bat \
  		src/Make_all.mak \
! 		src/README.md \
  		src/alloc.h \
  		src/arabic.c \
  		src/ascii.h \
*** ../vim-8.1.1068/src/version.c	2019-03-29 12:19:34.953348924 +0100
--- src/version.c	2019-03-29 12:55:49.505486487 +0100
***************
*** 777,778 ****
--- 777,780 ----
  {   /* Add new patch number below this line */
+ /**/
+     1069,
  /**/

-- 
hundred-and-one symptoms of being an internet addict:
145. You e-mail your boss, informing him you'll be late.

 /// Bram Moolenaar -- Bram@Moolenaar.net -- http://www.Moolenaar.net   \\\
///        sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\  an exciting new programming language -- http://www.Zimbu.org        ///
 \\\            help me help AIDS victims -- http://ICCF-Holland.org    ///