To: vim_dev@googlegroups.com Subject: Patch 8.1.1069 Fcc: outbox From: Bram Moolenaar 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 or 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 ///