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 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 -- [email protected] -- 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 ///
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/d/optout.
