view doc/README @ 44594:c23877cb25a5 stable

darwin: use vim, not vi, to avoid data-loss inducing posix behavior

Apple's version of vim, available at
opensource.apple.com/release/macos-1015.html (for Catalina, but this behavior
has been there for a while) has several tweaks from the version of vim from
vim.org. Most of these tweaks appear to be for "Unix2003" compatibility.

One of the tweaks is that if any ex command raises an error, the entire
process will (when you exit, possibly minutes/hours later) also exit non-zero.
Ex commands are things like `:foo`.

Luckily, they only enabled this if vim was executed (via a symlink or copying
the binary) as `vi` or `ex`. If you start it as `vim`, it doesn't have this
behavior, so let's do that.

To see this in action, run the following two commands on macOS:

```
  $ vi -c ':unknown' -c ':qa' ; echo $?
  1
  $ vim -c ':unknown' -c ':qa' ; echo $?
  0
```

We don't want to start ignoring non-zero return types from the editor because
that will mean you can't use `:cquit` to intentionally exit 1 (which,
shows up as 2 if you combine an ex command error and a cquit, but only a 1 if
you just use cquit, so we can't differentiate between the two statuses). Since
we can't differentiate, we have to assume that all non-zero exit codes are
intentional and an indication of the user's desire to not continue with whatever
we're doing. If this was a complicated `hg split` or `hg histedit`, this is
especially disastrous :(

Differential Revision: https://phab.mercurial-scm.org/D8321

Mercurial's documentation is kept in reStructuredText format, which is
a simple plain text format that's easy to read and edit:

  http://docutils.sourceforge.net/rst.html

It's also convertible to a variety of other formats including standard
UNIX man page format and HTML. You'll need to install Docutils:

  http://docutils.sourceforge.net/

Use the Makefile in this directory to generate the man and HTML pages.