docs: add wiki FAQ to the runtime documentation (#26539)

Problem: Wiki contents are not discoverable and hard to maintain.
Solution: Move FAQ to runtime docs.

Co-authored-by: Christian Clason <c.clason@uni-graz.at>

8 files changed, 686 insertions, 6 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a95ca58ed2..f14eee9bc7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ Reporting problems
 - If a specific configuration or plugin is necessary to recreate the problem, use the minimal template in `contrib/minimal.lua` with `nvim --clean -u contrib/minimal.lua` after making the necessary changes.
 - [Bisect](https://neovim.io/doc/user/starting.html#bisect) your config: disable plugins incrementally, to narrow down the cause of the issue.
 - [Bisect][git-bisect] Neovim's source code to find the cause of a regression, if you can. This is _extremely_ helpful.
-- When reporting a crash, [include a stacktrace](https://github.com/neovim/neovim/wiki/FAQ#backtrace-linux).
+- When reporting a crash, [include a stacktrace](https://neovim.io/doc/user/faq.html#backtrace-linux).
 - Use [ASAN/UBSAN](#clang-sanitizers-asan-and-ubsan) to get detailed errors for segfaults and undefined behavior.
 - Check the logs. `:edit $NVIM_LOG_FILE`
 - Include `cmake --system-information` for build-related issues.
@@ -347,4 +347,4 @@ as context, use the `-W` argument as well.
 [pr-ready]: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request
 [run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
 [style-guide]: https://neovim.io/doc/user/dev_style.html#dev-style
-[wiki-faq]: https://github.com/neovim/neovim/wiki/FAQ
+[wiki-faq]: https://neovim.io/doc/user/faq.html
diff --git a/runtime/doc/dev_tools.txt b/runtime/doc/dev_tools.txt
new file mode 100644
index 0000000000..f222930e99
--- /dev/null
+++ b/runtime/doc/dev_tools.txt
@@ -0,0 +1,192 @@
+*dev_tools.txt*          Nvim
+
+
+                            NVIM REFERENCE MANUAL
+
+
+Tools and techniques for developing Nvim                        *dev-tools*
+
+The following advice is helpful when working on or debugging issues with Nvim
+itself. See also |debug.txt| for advice that applies to Vim.
+
+                                  Type |gO| to see the table of contents.
+
+==============================================================================
+Backtraces                                            *dev-tools-backtrace*
+
+LINUX ~
+
+Core dumps are disabled by default on Ubuntu
+https://stackoverflow.com/a/18368068, CentOS and others. To enable core dumps:
+>bash
+    ulimit -c unlimited
+<
+On systemd-based systems getting a backtrace is as easy as:
+>bash
+    coredumpctl -1 gdb
+<
+It's an optional tool, so you may need to install it:
+>bash
+    sudo apt install systemd-coredump
+<
+
+The full backtrace is most useful, send us the `bt.txt` file:
+>bash
+    2>&1 coredumpctl -1 gdb | tee -a bt.txt
+    thread apply all bt full
+<
+On older systems a `core` file will appear in the current directory. To get
+a backtrace from the `core` file:
+>bash
+    gdb build/bin/nvim core 2>&1 | tee backtrace.txt
+    thread apply all bt full
+<
+
+MACOS
+
+If `nvim` crashes, you can see the backtrace in `Console.app` (under "Crash
+Reports" or "User Diagnostic Reports" for older macOS versions).
+>bash
+    open -a Console
+<
+You may also want to enable core dumps on macOS. To do this, first make sure
+the `/cores/` directory exists and is writable:
+>bash
+    sudo mkdir /cores
+    sudo chown root:admin /cores
+    sudo chmod 1775 /cores
+<
+Then set the core size limit to `unlimited`:
+>bash
+    ulimit -c unlimited
+<
+Note that this is done per shell process. If you want to make this the default
+for all shells, add the above line to your shell's init file (e.g. `~/.bashrc`
+or similar).
+
+You can then open the core file in `lldb`:
+>bash
+    lldb -c /cores/core.12345
+<
+Apple's documentation archive has some other useful information
+https://developer.apple.com/library/archive/technotes/tn2124/_index.html#//apple_ref/doc/uid/DTS10003391-CH1-SECCOREDUMPS,
+but note that some of the things on this page are out of date (such as enabling
+core dumps with `/etc/launchd.conf`).
+
+==============================================================================
+Gdb                                                          *dev-tools-gdb*
+
+USING GDB TO STEP THROUGH FUNCTIONAL TESTS ~
+
+Use `TEST_TAG` to run tests matching busted tags (of the form `#foo` e.g.
+`it("test #foo ...", ...)`):
+>bash
+    GDB=1 TEST_TAG=foo make functionaltest
+<
+Then, in another terminal:
+>bash
+    gdb build/bin/nvim
+    target remote localhost:7777
+<
+- See also test/functional/helpers.lua https://github.com/neovim/neovim/blob/3098b18a2b63a841351f6d5e3697cb69db3035ef/test/functional/helpers.lua#L38-L44.
+
+
+USING LLDB TO STEP THROUGH UNIT TESTS ~
+
+>bash
+    lldb .deps/usr/bin/luajit -- .deps/usr/bin/busted --lpath="./build/?.lua" test/unit/
+<
+
+USING GDB ~
+
+To attach to a running `nvim` process with a pid of 1234:
+>bash
+    gdb -tui -p 1234 build/bin/nvim
+<
+The `gdb` interactive prompt will appear. At any time you can:
+
+- `break foo` to set a breakpoint on the `foo()` function
+- `n` to step over the next statement
+    - `<Enter>` to repeat the last command
+- `s` to step into the next statement
+- `c` to continue
+- `finish` to step out of the current function
+- `p zub` to print the value of `zub`
+- `bt` to see a backtrace (callstack) from the current location
+- `CTRL-x CTRL-a` or `tui enable` to show a TUI view of the source file in the
+  current debugging context. This can be extremely useful as it avoids the
+  need for a gdb "frontend".
+- `<up>` and `<down>` to scroll the source file view
+
+
+GDB "REVERSE DEBUGGING" ~
+
+- `set record full insn-number-max unlimited`
+- `continue` for a bit (at least until `main()` is executed
+- `record`
+- provoke the bug, then use `revert-next`, `reverse-step`, etc. to rewind the
+  debugger
+
+
+USING GDBSERVER ~
+
+You may want to connect multiple `gdb` clients to the same running `nvim`
+process, or you may want to connect to a remote `nvim` process with a local
+`gdb`. Using `gdbserver`, you can attach to a single process and control it
+from multiple `gdb` clients.
+
+Open a terminal and start `gdbserver` attached to `nvim` like this:
+>bash
+    gdbserver :6666 build/bin/nvim 2> gdbserver.log
+<
+`gdbserver` is now listening on port 6666. You then need to attach to this
+debugging session in another terminal:
+>bash
+    gdb build/bin/nvim
+<
+Once you've entered `gdb`, you need to attach to the remote session:
+>
+    target remote localhost:6666
+<
+In case gdbserver puts the TUI as a background process, the TUI can become
+unable to read input from pty (and receives SIGTTIN signal) and/or output data
+(SIGTTOU signal). To force the TUI as the foreground process, you can add
+>
+    signal (SIGTTOU, SIG_IGN);
+    if (!tcsetpgrp(data->input.in_fd, getpid())) {
+        perror("tcsetpgrp failed");
+    }
+<
+to `tui.c:terminfo_start`.
+
+
+USING GDBSERVER IN TMUX ~
+
+Consider using a custom makefile
+https://github.com/neovim/neovim/wiki/Building-Neovim#custom-makefile to
+quickly start debugging sessions using the `gdbserver` method mentioned above.
+This example `local.mk` will create the debugging session when you type
+`make debug`.
+>make
+    .PHONY: dbg-start dbg-attach debug build
+
+    build:
+        @$(MAKE) nvim
+
+    dbg-start: build
+        @tmux new-window -n 'dbg-neovim' 'gdbserver :6666 ./build/bin/nvim -D'
+
+    dbg-attach:
+        @tmux new-window -n 'dbg-cgdb' 'cgdb -x gdb_start.sh ./build/bin/nvim'
+
+    debug: dbg-start dbg-attach
+<
+Here `gdb_start.sh` includes `gdb` commands to be called when the debugger
+starts. It needs to attach to the server started by the `dbg-start` rule. For
+example:
+>
+    target remote localhost:6666
+    br main
+<
+
+vim:tw=78:ts=8:et:ft=help:norl:
diff --git a/runtime/doc/faq.txt b/runtime/doc/faq.txt
new file mode 100644
index 0000000000..1e9dc052a1
--- /dev/null
+++ b/runtime/doc/faq.txt
@@ -0,0 +1,485 @@
+*faq.txt*		 Nvim
+
+                            NVIM REFERENCE MANUAL
+
+
+Frequently asked Questions                                        *faq*
+
+                                  Type |gO| to see the table of contents.
+
+==============================================================================
+General Questions                                                 *faq-general*
+
+
+WHERE SHOULD I PUT MY CONFIG (VIMRC)? ~
+
+See |config|; you can copy (or symlink) your existing vimrc. |nvim-from-vim|
+
+
+HOW STABLE IS THE DEVELOPMENT (PRE-RELEASE) VERSION? ~
+
+The unstable (pre-release)
+https://github.com/neovim/neovim/releases/tag/nightly version of Nvim
+("HEAD", i.e. the `master` branch) is used to aggressively stage new features
+and changes. It's usually stable, but will occasionally break your workflow.
+We depend on HEAD users to report "blind spots" that were not caught by
+automated tests.
+
+Use the stable (release) https://github.com/neovim/neovim/releases/latest
+version for a more predictable experience.
+
+
+CAN I USE RUBY-BASED VIM PLUGINS (E.G. LUSTYEXPLORER)? ~
+
+Yes, starting with Nvim 0.1.5 PR #4980
+https://github.com/neovim/neovim/pull/4980 the legacy Vim `if_ruby` interface
+is supported.
+
+
+CAN I USE LUA-BASED VIM PLUGINS (E.G. NEOCOMPLETE)? ~
+
+No. Starting with Nvim 0.2 PR #4411
+https://github.com/neovim/neovim/pull/4411 Lua is built-in, but the legacy
+Vim `if_lua` interface is not supported.
+
+
+HOW CAN I USE "TRUE COLOR" IN THE TERMINAL? ~
+
+Truecolor (24bit colors) are enabled by default if a supporting terminal is
+detected. If your terminal is not detected but you are sure it supports
+truecolor, add this to your |init.vim|:
+>vim
+    set termguicolors
+<
+
+NVIM SHOWS WEIRD SYMBOLS (`�[2 q`) WHEN CHANGING MODES ~
+
+This is a bug in your terminal emulator. It happens because Nvim sends
+cursor-shape termcodes by default, if the terminal appears to be
+xterm-compatible (`TERM=xterm-256color`).
+
+To workaround the issue, you can:
+
+- Use a different terminal emulator
+- Disable 'guicursor' in your Nvim config: >vim
+
+    :set guicursor=
+    " Workaround some broken plugins which set guicursor indiscriminately.
+    :autocmd OptionSet guicursor noautocmd set guicursor=
+<
+See also |$TERM| for recommended values of `$TERM`.
+
+
+HOW TO CHANGE CURSOR SHAPE IN THE TERMINAL? ~
+
+- For Nvim 0.1.7 or older: see the note about `NVIM_TUI_ENABLE_CURSOR_SHAPE` in `man nvim`.
+- For Nvim 0.2 or newer: cursor styling is controlled by the 'guicursor' option.
+    - To _disable_ cursor-styling, set 'guicursor' to empty: >vim
+
+            :set guicursor=
+            " Workaround some broken plugins which set guicursor indiscriminately.
+            :autocmd OptionSet guicursor noautocmd set guicursor=
+<
+    - If you want a non-blinking cursor, use `blinkon0`. See 'guicursor'.
+    - 'guicursor' is enabled by default, unless Nvim thinks your terminal doesn't
+        support it. If you're sure that your terminal supports cursor-shaping, set
+        'guicursor' in your |init.vim|, as described in 'guicursor'.
+- The Vim terminal options |t_SI| and `t_EI` are ignored, like all other |t_xx| options.
+- Old versions of libvte (gnome-terminal, roxterm, terminator, ...) do not
+  support cursor style control codes. #2537
+  https://github.com/neovim/neovim/issues/2537
+
+
+HOW TO CHANGE CURSOR COLOR IN THE TERMINAL? ~
+
+Cursor styling (shape, color, behavior) is controlled by 'guicursor', even in
+the terminal. Cursor color (as opposed to shape) only works if
+'termguicolors' is set.
+
+'guicursor' gives an example, but here's a more complicated example
+which sets different colors in insert-mode and normal-mode:
+>vim
+    :set termguicolors
+    :hi Cursor guifg=green guibg=green
+    :hi Cursor2 guifg=red guibg=red
+    :set guicursor=n-v-c:block-Cursor/lCursor,i-ci-ve:ver25-Cursor2/lCursor2,r-cr:hor20,o:hor50
+<
+
+CURSOR STYLE ISN'T RESTORED AFTER EXITING OR SUSPENDING AND RESUMING NVIM ~
+
+Terminals do not provide a way to query the cursor style. Use autocommands to
+manage the cursor style:
+>vim
+    au VimEnter,VimResume * set guicursor=n-v-c:block,i-ci-ve:ver25,r-cr:hor20,o:hor50
+      \,a:blinkwait700-blinkoff400-blinkon250-Cursor/lCursor
+      \,sm:block-blinkwait175-blinkoff150-blinkon175
+
+    au VimLeave,VimSuspend * set guicursor=a:block-blinkon0
+<
+
+CURSOR SHAPE DOESN'T CHANGE IN TMUX ~
+
+tmux decides that, not Nvim. See |tui-cursor-shape| for a fix.
+
+See #3165 https://github.com/neovim/neovim/pull/3165 for discussion.
+
+
+CURSOR FLICKER IN TMUX? ~
+
+If cursor `_` appears and disappears very quickly when opening nvim without a
+document under tmux, and you set |ctermbg| in `EndOfBuffer` and `Normal`, try
+setting these to `NONE`:
+>vim
+    hi EndOfBuffer ctermbg=NONE ctermfg=200 cterm=NONE
+    hi Normal ctermbg=NONE ctermfg=200 cterm=NONE
+<
+
+WHAT HAPPENED TO --remote AND FRIENDS? ~
+
+|--remote| is partly supported. |clientserver|
+
+If you require flags from Vim that are missing in Nvim, you can use
+https://github.com/mhinz/neovim-remote instead.
+
+==============================================================================
+Runtime issues                                                *faq-runtime*
+
+
+COPYING TO X11 PRIMARY SELECTION WITH THE MOUSE DOESN'T WORK ~
+
+`clipboard=autoselect` is not implemented yet
+https://github.com/neovim/neovim/issues/2325. You may find this workaround to
+be useful:
+>vim
+    vnoremap <LeftRelease> "*ygv
+    vnoremap <2-LeftRelease> "*ygv
+<
+
+MY CTRL-H MAPPING DOESN'T WORK ~
+
+This was fixed in Nvim 0.2. If you are running Nvim 0.1.7 or older,
+adjust your terminal's "kbs" (key_backspace) terminfo entry:
+>vim
+    infocmp $TERM | sed 's/kbs=^[hH]/kbs=\\177/' > $TERM.ti
+    tic $TERM.ti
+<
+(Feel free to delete the temporary `*.ti` file created after running the above
+commands).
+
+
+<HOME> OR SOME OTHER "SPECIAL" KEY DOESN'T WORK ~
+
+Make sure |$TERM| is set correctly.
+
+- For screen or tmux, `$TERM` should be `screen-256color` (not `xterm-256color`!)
+- In other cases if "256" does not appear in the string it's probably wrong.
+  Try `TERM=xterm-256color`.
+
+
+:! AND SYSTEM() DO WEIRD THINGS WITH INTERACTIVE PROCESSES ~
+
+Interactive commands are supported by |:terminal| in Nvim. But |:!| and
+|system()| do not support interactive commands, primarily because Nvim UIs use
+stdio for msgpack communication, but also for performance, reliability, and
+consistency across platforms (see
+https://vimhelp.org/gui_x11.txt.html#gui-pty).
+
+See also #1496 https://github.com/neovim/neovim/issues/1496 and #8217
+https://github.com/neovim/neovim/issues/8217#issuecomment-402152307.
+
+
+PYTHON SUPPORT ISN'T WORKING ~
+
+Run |:checkhealth| in Nvim for automatic diagnosis.
+
+Other hints:
+
+- The python `neovim` module was renamed to `pynvim` (long ago).
+- If you're using pyenv or virtualenv for the `pynvim` module
+    https://pypi.python.org/pypi/pynvim/, you must set `g:python3_host_prog` to
+    the virtualenv's interpreter path.
+- Read |provider-python|.
+- Be sure you have the latest version of the `pynvim` Python module: >bash
+
+    python -m pip install setuptools
+    python -m pip install --upgrade pynvim
+    python3 -m pip install --upgrade pynvim
+<
+- Try with `nvim -u NORC` to make sure your config (|init.vim|) isn't causing a
+    problem. If you get `E117: Unknown function`, that means there's a runtime
+    issue: |faq-runtime|.
+
+
+:CHECKHEALTH REPORTS E5009: INVALID $VIMRUNTIME ~
+
+This means `health#check()` couldn't load, which suggests that |$VIMRUNTIME|
+or 'runtimepath' is broken.
+
+- |$VIMRUNTIME| must point to Nvim's runtime files, not Vim's.
+- The |$VIMRUNTIME| directory contents should be readable by the current user.
+- Verify that `:echo &runtimepath` contains the $VIMRUNTIME path.
+- Check the output of: >vim
+
+    :call health#check()
+    :verbose func health#check
+<
+
+NEOVIM CAN'T FIND ITS RUNTIME ~
+
+This is the case if `:help nvim` shows `E149: Sorry, no help for nvim`.
+
+Make sure that |$VIM| and |$VIMRUNTIME| point to Nvim's (as opposed to
+Vim's) runtime by checking `:echo $VIM` and `:echo $VIMRUNTIME`. This should
+give something like `/usr/share/nvim` resp. `/usr/share/nvim/runtime`.
+
+Also make sure that you don't accidentally overwrite your runtimepath
+(`:set runtimepath?`), which includes the above |$VIMRUNTIME| by default (see
+'runtimepath').
+
+
+NEOVIM IS SLOW ~
+
+
+Use a fast terminal emulator:
+
+- kitty https://github.com/kovidgoyal/kitty
+- alacritty https://github.com/jwilm/alacritty
+
+
+Use an optimized build:
+
+`:checkhealth nvim` should report one of these "build types":
+>
+    Build type: RelWithDebInfo
+    Build type: MinSizeRel
+    Build type: Release
+<
+If it reports `Build type: Debug` and you're building Nvim from source, see
+https://github.com/neovim/neovim/wiki/Building-Neovim.
+
+
+COLORS AREN'T DISPLAYED CORRECTLY ~
+
+Ensure that |$TERM| is set correctly.
+
+From a shell, run `TERM=xterm-256color nvim`. If colors are displayed
+correctly, then export that value of `TERM` in your user profile (usually
+`~/.profile`):
+>bash
+    export TERM=xterm-256color
+<
+If you're using `tmux`, instead add this to your `tmux.conf`:
+>bash
+    set -g default-terminal "tmux-256color"
+<
+
+For GNU `screen`, configure your `.screenrc`
+<https://wiki.archlinux.org/index.php/GNU_Screen#Use_256_colors>:
+>
+    term screen-256color
+<
+
+NOTE: Nvim ignores `t_Co` and other |t_xx| terminal codes.
+
+
+NEOVIM CAN'T READ UTF-8 CHARACTERS ~
+
+Run the following from the command line:
+>bash
+    locale | grep -E '(LANG|LC_CTYPE|LC_ALL)=(.*\.)?(UTF|utf)-?8'
+<
+If there's no results, then you might not be using a UTF-8 locale. See the
+following issues:
+#1601 https://github.com/neovim/neovim/issues/1601
+#1858 https://github.com/neovim/neovim/issues/1858
+#2386 https://github.com/neovim/neovim/issues/2386
+
+
+ESC IN TMUX OR GNU SCREEN IS DELAYED ~
+
+This is a common problem
+https://www.google.com/?q=tmux%20vim%20escape%20delay in `tmux` / `screen`
+(see also tmux/#131
+https://github.com/tmux/tmux/issues/131#issuecomment-145853211). The
+corresponding timeout needs to be tweaked to a low value (10-20ms).
+
+`.tmux.conf`:
+>
+    set -g escape-time 10
+    # Or for tmux >= 2.6
+    set -sg escape-time 10
+<
+`.screenrc`:
+>
+    maptimeout 10
+<
+
+"WHY DOESN'T THIS HAPPEN IN VIM?"
+
+It does happen (try `vim -N -u NONE`), but if you hit a key quickly after
+ESC_ then Vim interprets the ESC as ESC instead of ALT (META). You won't
+notice the delay unless you closely observe the cursor. The tradeoff is that
+Vim won't understand ALT (META) key-chords, so for example `nnoremap <M-a>`
+won't work. ALT (META) key-chords always work in Nvim. See also `:help
+xterm-cursor-keys` in Vim.
+
+Nvim 0.3 mimics the Vim behavior while still fully supporting ALT mappings. See
+|i_ALT|.
+
+
+ESC IN GNU SCREEN IS LOST WHEN MOUSE MODE IS ENABLED ~
+
+This happens because of a bug in screen https://savannah.gnu.org/bugs/?60196:
+in mouse mode, screen assumes that `ESC` is part of a mouse sequence and will
+wait an unlimited time for the rest of the sequence, regardless of
+`maptimeout`. Until it's fixed in screen, there's no known workaround for
+this other than double-pressing escape, which causes a single escape to be
+passed through to Nvim.
+
+
+CALLING INPUTLIST(), ECHOMSG, ... IN FILETYPE PLUGINS AND AUTOCMD DOES NOT WORK ~
+
+#10008 https://github.com/neovim/neovim/issues/10008,
+#10116 https://github.com/neovim/neovim/issues/10116,
+#12288 https://github.com/neovim/neovim/issues/12288,
+# vim/vim#4379 https://github.com/vim/vim/issues/4379.
+This is because Nvim sets `shortmess+=F` by default. Vim behaves the same way
+with `set shortmes+=F`. There are plans to improve this, but meanwhile as a
+workaround, use `set shortmess-=F` or use `unsilent` as follows.
+>vim
+    unsilent let var = inputlist(['1. item1', '2. item2'])
+    autocmd BufNewFile * unsilent echomsg 'The autocmd has been fired.'
+<
+
+G:CLIPBOARD SETTINGS ARE NOT USED. ~
+
+If the clipboard provider is already loaded, you will need to reload it after
+configuration. Use the following configuration.
+>vim
+    let g:clipboard = { 'name' : ... }
+    if exists('g:loaded_clipboard_provider')
+      unlet g:loaded_clipboard_provider
+      runtime autoload/provider/clipboard.vim
+    endif
+<
+
+Or, if you want automatic reloading when assigning to |g:clipboard|, set
+|init.vim| as follows.
+>vim
+    function! s:clipboard_changed(...) abort
+      if exists('g:loaded_clipboard_provider')
+        unlet g:loaded_clipboard_provider
+      endif
+      runtime autoload/provider/clipboard.vim
+    endfunction
+
+    if !exists('s:loaded")
+      call dictwatcheradd(g:, 'clipboard', function('s:clipboard_changed'))
+    endif
+    let s:loaded = v:true
+<
+
+==============================================================================
+Build issues                                                    *faq-build*
+
+
+GENERAL BUILD ISSUES ~
+
+Run `make distclean && make` to rule out a stale build environment causing the
+failure.
+
+
+SETTINGS IN LOCAL.MK DON'T TAKE EFFECT ~
+
+CMake caches build settings, so you might need to run `rm -r build && make`
+after modifying `local.mk`.
+
+
+CMAKE ERRORS ~
+
+`configure_file Problem configuring file`
+
+This is probably a permissions issue, which can happen if you run `make` as the
+root user, then later run an unprivileged `make`. To fix this, run `rm -rf
+build` and try again.
+
+
+GENERATING HELPTAGS FAILED ~
+
+If re-installation fails with "Generating helptags failed", try removing the
+previously installed runtime directory (if `CMAKE_INSTALL_PREFIX` is not set
+during building, the default is `/usr/local/share/nvim`):
+>bash
+    rm -r /usr/local/share/nvim
+<
+
+==============================================================================
+Design                                                         *faq-design*
+
+
+WHY NOT USE JSON FOR RPC? ~
+
+- JSON cannot easily/efficiently handle binary data
+- JSON specification is ambiguous: https://seriot.ch/parsing_json.php
+
+
+WHY EMBED LUA INSTEAD OF X? ~
+
+- Lua is a very small language, ideal for embedding. The biggest advantage of
+  Python/Ruby/etc is their huge collection of libraries, but that isn't
+  relevant for Nvim, where Nvim is the "batteries included" library:
+  introducing another stdlib would be redundant.
+- Lua 5.1 is a complete language: the syntax is frozen. This is great for
+  backwards compatibility.
+- Nvim also uses Lua internally as an alternative to C. Extra performance is
+  useful there, as opposed to a slow language like Python or Vim9script.
+- LuaJIT is one of the fastest runtimes on the planet, 10x faster than Python
+  and "Vim9script" https://vimhelp.org/vim9.txt.html, 100x faster than
+  Vimscript.
+- Python/JS cost more than Lua in terms of size and portability, and there are
+  already numerous Python/JS-based editors. So Python/JS would make Nvim
+  bigger and less portable, in exchange for a non-differentiating feature.
+
+See also:
+
+- Why Lua https://web.archive.org/web/20150219224654/https://blog.datamules.com/blog/2012/01/30/why-lua/
+- The Design of Lua https://cacm.acm.org/magazines/2018/11/232214-a-look-at-the-design-of-lua/fulltext
+- Scripting architecture considerations http://oldblog.antirez.com/post/redis-and-scripting.html
+- LuaJIT performance https://julialang.org/benchmarks/
+- Discussion of JavaScript vs Lua https://github.com/vim/vim/pull/5198#issuecomment-554693754
+- Discussion Python embedding https://lobste.rs/s/pnuak4/mercurial_s_journey_reflections_on#c_zshdwy
+
+
+WHY LUA 5.1 INSTEAD OF LUA 5.3+? ~
+
+Lua 5.1 is a different language than 5.3. The Lua org makes breaking changes
+with every new version, so even if we switched (not upgraded, but switched) to
+5.3 we gain nothing when they create the next new language in 5.4, 5.5, etc.
+And we would lose LuaJIT, which is far more valuable than Lua 5.3+.
+
+Lua 5.1 is a complete language. To "upgrade" it, add libraries, not syntax.
+Nvim itself already is a pretty good "stdlib" for Lua, and we will continue to
+grow and enhance it. Changing the rules of Lua gains nothing in this context.
+
+
+WILL NEOVIM TRANSLATE VIMSCRIPT TO LUA, INSTEAD OF EXECUTING VIMSCRIPT DIRECTLY? ~
+
+- We are experimenting with vim9jit https://github.com/tjdevries/vim9jit to
+  transpile Vim9script (Vim9's Vimscript variant) to Lua and have used this to
+  port Vim9 plugins https://github.com/neovim/neovim/pull/21662 to Nvim Lua.
+- We have no plans for transpiling legacy Vimscript.
+
+
+ARE PLUGIN AUTHORS ENCOURAGED TO PORT THEIR PLUGINS FROM VIMSCRIPT TO LUA? DO YOU PLAN ON SUPPORTING VIMSCRIPT INDEFINITELY? (#1152) ~
+
+We don't anticipate any reason to deprecate Vimscript, which is a valuable DSL
+https://en.wikipedia.org/wiki/Domain-specific_language for text-editing tasks.
+Maintaining Vimscript compatibility is less costly than a mass migration of
+existing Vim plugins.
+
+Porting from Vimscript to Lua just for the heck of it gains nothing. Nvim is
+emphatically a fork of Vim in order to leverage the work already spent on
+thousands of Vim plugins, while enabling new types of plugins and
+integrations.
+
+vim:tw=78:ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index b8526b55e9..47ae413714 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -47,6 +47,7 @@ ABOUT NVIM				*reference_toc* *doc-file-list* *Q_ct*
 |news|			News since the previous release
 |nvim|			Transitioning from Vim
 |vim-differences|	Nvim compared to Vim
+|faq|			Frequently Asked Questions
 |user-manual|		User manual: How to accomplish editing tasks.
 |quickref|		Overview of common commands
 |tutor|			30-minute interactive course for beginners
@@ -167,7 +168,8 @@ DEVELOPING NVIM
 
 |dev|			Development of Nvim
 |dev-style|		Development style guidelines
-|debug.txt|		Debugging Vim itself
+|dev-theme|		Design guidelines (colorschemes etc.)
+|dev-tools|		Tools and techniques for developing Nvim
 
 Standard plugins ~
 						*standard-plugin-list*
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index 85115fc22b..c9211291d0 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -49,10 +49,9 @@ For more information try one of these:
 ==============================================================================
 Nvim on the interwebs					*internet*
 
-			*www* *faq* *distribution* *download*
+			*www* *distribution* *download*
 
 	Nvim home page:	  https://neovim.io/
-	Nvim FAQ:	  https://github.com/neovim/neovim/wiki/FAQ
 	Downloads:	  https://github.com/neovim/neovim/releases
 	Vim FAQ:	  https://vimhelp.org/vim_faq.txt.html
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 355c8cc99a..fda60eaab2 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -30,6 +30,7 @@ achieve special effects.  These options come in three forms:
 
 								*E518* *E519*
 :se[t] {option}?	Show value of {option}.
+			NOTE: some legacy options were removed. |nvim-removed|
 
 :se[t] {option}		Toggle option: set, switch it on.
 			Number option: show value.
diff --git a/runtime/nvim.appdata.xml b/runtime/nvim.appdata.xml
index 29db9d5ee4..bff8bc4bff 100644
--- a/runtime/nvim.appdata.xml
+++ b/runtime/nvim.appdata.xml
@@ -56,7 +56,7 @@
   <launchable type="desktop-id">nvim.desktop</launchable>
   <url type="homepage">https://neovim.io/</url>
   <url type="bugtracker">https://github.com/neovim/neovim/issues</url>
-  <url type="faq">https://github.com/neovim/neovim/wiki/FAQ</url>
+  <url type="faq">https://neovim.io/doc/user/faq.html</url>
   <url type="help">https://neovim.io/doc/</url>
   <url type="donation">https://neovim.io/#sponsor</url>
   <url type="translate">https://github.com/neovim/neovim/tree/master/src/nvim/po</url>
diff --git a/scripts/gen_help_html.lua b/scripts/gen_help_html.lua
index 9369711b0f..8226a0548f 100644
--- a/scripts/gen_help_html.lua
+++ b/scripts/gen_help_html.lua
@@ -80,6 +80,7 @@ local exclude_invalid_urls = {
   ['http://wiki.services.openoffice.org/wiki/Dictionaries'] = 'spell.txt',
   ['http://www.adapower.com'] = 'ft_ada.txt',
   ['http://www.jclark.com/'] = 'quickfix.txt',
+  ['http://oldblog.antirez.com/post/redis-and-scripting.html'] = 'faq.txt',
 }
 
 -- Deprecated, brain-damaged files that I don't care about.