README.md: Reword with friendlier language

1 files changed, 80 insertions, 201 deletions

diff --git a/README.md b/README.md
index b2309f5..6ec6a58 100644
--- a/README.md
+++ b/README.md
@@ -1,220 +1,99 @@
 # The Mana World Athena
-
 ![The Mana World logo](share/tmwa/TheManaWorldLogo.png)
+Welcome to The Mana World Athena! This is an MMORPG server used by The Mana World, based on a protocol that was inspired by the project named "Athena". In 2004, it was forked from eAthena, a Ragnarok Online clone.
+
+
+If you are interested in contributing, please take a look at our [wiki](http://wiki.themanaworld.org/index.php/Development:How_to_Develop) for user instructions. It provides detailed information on how to get started.
+
+**Important note:** Building from a GitHub-generated tarball does not work! You must either build from a git checkout or from a 'make dist' tarball.
+
+The rest of this file contains information relevant to distributors and contributors.
+
+## 1. Distributors
+### Important notes
+- Please read [version.make](version.make) for important version information.
+- TMWA requires git to build by default. Use 'make dist' to get a tarball.
+
+### Platform dependencies
+#### Architecture
+- Tested: x86, amd64, x32
+- Likely to work: all architectures (patches welcome if they don't)
+
+#### Operating system
+- Known bad: Linux 2.6.26 and earlier
+- Maintained: Linux 3.2 and later
+- Likely to break: Cygwin, BSD
+
+#### Filesystem
+- Must support symlinks
+
+### Build dependencies
+#### Python
+- Required: 2.7.x only, installed in $PATH as 'python'
+
+#### C library
+- Recommended: glibc 2.17 or higher
+- Supported: glibc 2.13
+- Known bad: glibc 2.8 or below
+- Unsupported: anything that's not glibc
+
+#### C++ compiler
+- Required: g++ 4.7.2 or higher
+- Recommended: g++ 4.8.1 or higher
+- Not recommended: clang++ 3.3 or higher (all versions have unfixed bugs)
 
-This is TMWA, an MMORPG server used by The Mana World that uses a protocol
-based on one of many projects that foolishly chose the name "Athena".
-Specifically, it was forked from eAthena, a Ragnarok Online clone, in 2004.
-
-Take a look at the [wiki](http://wiki.themanaworld.org/index.php/How_to_Develop) for user instructions.
-
-**Important note:** building from a GitHub-generated tarball does not work!
-You must either build from a git checkout or from a 'make dist' tarball.
-
-
-The rest of this file contains information relevant only to:
-
-1. Distributors.
-2. Contributors.
-
-TMWA has a [bugtracker](https://git.themanaworld.org/legacy/tmwa/-/issues).
-
-But it's probably worth getting on IRC first:
-* Use an IRC client: irc://irc.libera.chat/themanaworld-dev
-* Or just use the [webchat](https://web.libera.chat/?channel=#themanaworld-dev).
-
-Note that this channel is not specific to technical discussion of TMWA (and
-attoconf), but for any discussions related to TMW development.
-
-## 1. Distributors.
-### Important notes:
-
-- Go read [version.make](version.make)
-- TMWA requires git to build by default, use 'make dist' to get a tarball.
-
-### Platform dependencies:
-#### Architecture:
-
-    tested: x86, amd64, x32
-    likely to work: all architectures (patches welcome if they don't)
-
-#### Operating system:
-    known bad: Linux 2.6.26 and earlier
-    maintained: Linux 3.2 and later
-    likely to break: Cygwin, BSD
-#### Filesystem:
-    must support symlinks
-
-### Build dependencies:
-#### Python:
-    required: 2.7.x only, installed in $PATH as 'python'
-#### C library:
-    recommended: glibc 2.17 or higher
-    supported: glibc 2.13
-    known bad: glibc 2.8 or below
-    unsupported: anything that's not glibc
-#### C++ compiler:
-    required: g++ 4.7.2 or higher
-    recommended: g++ 4.8.1 or higher
-    not recommended: clang++ 3.3 or higher (all versions have unfixed bugs)
-#### C++ library:
-    recommended: libstdc++ to match g++; may need patch for clang++
-    may work: libc++
-#### attoconf:
-    special: see below
-### Runtime dependencies:
-#### glibc:
-    depends on what it was built against
-#### libstdc++:
-    depends on what it was built against
-### Instructions:
-#### Configuration:
-    ./configure
-_Takes most of the options GNU Autoconf's configure does - I won't
-    repeat the output of `./configure --help` here._
-
-_`--prefix=/usr`, not `--prefix usr`, in order to prevent an ambiguity.
-    "In the face of ambiguity, refuse the temptation to guess."_
-
-_Out-of-tree builds work._
-
-_Note that there is no option to disable dependency tracking, as it
-    is also used to generate link information. There is also no option
-    to ignore unknown options - I refuse to lie._
-#### Build:
-    make -jN
-#### Build test:
-    make test
-
-_Nowhere near complete useful yet. Requires source of Google Test._
+#### C++ library
+- Recommended: libstdc++ to match g++; may need patch for clang++
+- May work: libc++
 
-    make format; git diff --exit-code
-#### Install:
-    make install DESTDIR=/whatever
-
-_See [what is installed](#what-is-installed) below_
-#### Install test:
-_not implemented_
-#### Distribution tarballs:
-    make dist
-    make bindist
-
-### Note about attoconf:
-TMWA's `./configure` script is implemented using a python package
-'attoconf', which I wrote over a weekend after reading GNU autoconf's
-documentation and realizing that it was 1. insane, and 2. still trying
-to solve the wrong sort of problem.
-
-Currently, attoconf's API is still in the "experimental" stage, so the
-real rule is "does ./configure work?".
-When it gets to 1.0, it will start guaranteeing compatibility.
-
-Attoconf is available at [Github](https://github.com/o11c/attoconf/) and is a
-well-behaving python package.
-
-Attoconf requires Python 2.7; a port to Python 2.6 is doable with a bit
-of work, but it is not known if this would benefit anybody.
-
-If you're Arch - you broke Python for us all, you clean up your own mess.
-Patches to call a nonexistent `/usr/bin/python2` will NOT be accepted.
-
-### What is installed:
-#### Overview:
-Currently, `make install` installs 5 binaries, along with a handful
-of libraries, headers, data files, config files, and debug files, each
-of which has a `make install-something` target.
-
-The 4 main programs below are typically running on the same machine,
-though in theory they may be configured to run on different machines
-in a fast LAN. Also, the internal protocol between the programs is
-subject to change without notice, so they *must* be upgraded
-simultaneously.
-
-These programs currently read most of their files relative to the
-current working directory; this was the only thing that makes sense
-since the files are dependent on the server-data. However, a migration
-to installed files has begun.
-
-#### tmwa-admin:
-Formerly known as `ladmin` ("local").
-
-This is an essential tool to maintain the server's flatfile "databases".
-It doesn't actually touch the files directly, just connects to
-tmwa-login.
-
-Even when everything is rewritten to use SQL, it will be kept, if just
-to keep a consistent interface. In fact, if we use SQLite we *can't*
-edit the databases independently. This wouldn't be a problem with
-Postgres, but people seem to think it's hard to install (that's not my
-experience on Debian though. Did they ever try themselves, or are they
-just repeating what they've heard?)
-
-#### tmwa-login:
-Formerly known as `login-server`.
-
-User-facing server to deal with account checks.
-
-Also accepts internal connections from `tmwa-admin` and `tmwa-char`,
-subject to a plaintext password (and for `tmwa-admin`, also an IP check).
-
-#### tmwa-char:
-Formerly known as `char-server`.
-
-User-facing server to deal with character persistence.
-
-Connects to `tmwa-login`; also takes internal connections from `tmwa-map`.
+#### attoconf
+- Special: see below
 
-Note that it is fully supported for more than one `tmwa-char` to connect
-to the same `tmwa-login`; the client will be presented with a list of
-"worlds" before leaving the login server.
+### Runtime dependencies
+#### glibc
+- Depends on what it was built against
 
-#### tmwa-map:
-Formerly known as `map-server`.
+#### libstdc++
+- Depends on what it was built against
 
-Connects to `tmwa-char`.
+### Instructions
+#### Configuration
+- Run `./configure` to configure the build. Most of the options are similar to GNU Autoconf's configure. For example, you can create a `build` directory and run `../configure` from there to keep the source directory clean.
 
-It is technically possible for more than one `tmwa-map` to connect to
-a single tmwa-char, but this is poorly supported by our current config
-and moderation tools, and there are likely undiscovered bugs.
+#### Build
+- Run `make -j$(nproc)` to build the project.
 
-#### About server data:
-Just having the binaries is not enough: you also need a complete set of
-content: config files, game scripts, savefiles, and client updates.
+#### Build test
+- Run `make test` to run the build tests. This requires Google Test available - it's added here as a submodule. Note that test coverage is not yet complete.
+- Run `make format` to format the code.
 
-A web server to serve the updates is also strongly recommended, as even
-developers get annoyed when wushin makes us work straight from his
-client-data repo.
+#### Install
+- Run `make install DESTDIR=/whatever` to install the project. See [what is installed](#what-is-installed) below.
 
-Currently, there is only *one* set of server data that is known to be
-compatible with TMWA: https://git.themanaworld.org/legacy/serverdata
+#### Install test
+- Not implemented
 
-The only recommended way of using this is by following the instructions
-in the [How to Develop](https://wiki.themanaworld.org/index.php/Dev:How_to_Develop) article. These instructions are only designed
-for people contributing to TMW itself, not to people trying to start
-a fork - we know all forks are doomed to be unsuccessful anyway, so
-please don't split the development effort, and you can't split the
-player community.
+#### Distribution tarballs
+- Run `make dist` or `make bindist` to create distribution tarballs.
 
-In particular, the instructions do NOT provide information on how to
-secure a server by changing all the default passwords.
+### Note about attoconf
+TMWA's `./configure` script is implemented using a python package called 'attoconf'. It provides a simpler alternative to GNU autoconf. Attoconf is available at [Github](https://github.com/o11c/attoconf/) and is a well-behaving python package. Please note that attoconf requires Python 2.7, however efforts to bring it to Python 3 are in progress.
 
-There are 3 other known sets of complete server data: regional ones
-for Germany and Brasil, and Evol. Evol requires their own fork of
-the tmwa server (for some reason they don't like me to call it evola),
-and nobody seems to know of the foreign servers are keeping active.
+### What is installed
+#### Overview
+Currently, `make install` installs 5 binaries, along with libraries, headers, data files, config files, and debug files. Each component has a specific `make install-something` target.
 
-Note also that The Mana World has not investigated the copyright status
-of other sets of server data.
+The 4 main programs listed below are typically running on the same machine, but they can be configured to run on different machines in a fast LAN. Please note that the internal protocol between the programs may change without notice, so it's important to upgrade them simultaneously.
 
-## 2. Contributors.
+- `tmwa-admin`: Formerly known as `ladmin` ("local"). This tool is used to maintain the server's flatfile "databases". It connects to `tmwa-login` to make changes.
+- `tmwa-login`: Formerly known as `login-server`. This server handles account checks and accepts internal connections from `tmwa-admin` and `tmwa-char`.
+- `tmwa-char`: Formerly known as `char-server`. This server handles character persistence, connects to `tmwa-login`, and accepts connections from `tmwa-map`. Multiple instances of `tmwa-char` can connect to the same `tmwa-login`. If this is the case, the client will be presented with a choice of worlds before leaving the login server. The Mana World sometimes runs a test `tmwa-char` server connected to the main `tmwa-login` for ease of access.
+- `tmwa-map`: Formerly known as `map-server`. This server connects to `tmwa-char`. Multiple instances of `tmwa-map` can connect to the same `tmwa-char`, with clients able to switch servers if they move to a map handled by a different map server. This has not been used by The Mana World, and may not work properly.
 
-You're welcome to help maintain this server, but please make sure to
-get in touch with the currently active maintainers first.
+#### About server data
+To run the server, you will need a complete set of content including config files, game scripts, savefiles, and client updates. We strongly recommend setting up a web server to serve the updates. You can find a compatible set of server data at https://git.themanaworld.org/legacy/serverdata. Please follow the instructions in the [How to Develop](https://wiki.themanaworld.org/index.php/Development:How_to_Develop) article for more information.
 
-Remember that this server is what currently keeps The Mana World alive,
-so any changes should be made with extreme care. It is important that
-each change be tested and reviewed before it goes live.
+## 2. Contributors
+We welcome contributions from developers like you! If you are interested in maintaining this server, please get in touch with the currently active maintainers first. It's important to make changes with extreme care and ensure that each change is thoroughly tested and reviewed before it goes live.
 
-Finally, if you got yourself somewhat familiar with this code, please
-consider sticking around either to fix further issues as they come up
-or to help reviewing changes by others. Thanks!
+If you have become familiar with the codebase, we encourage you to stick around and help fix issues or review changes made by others. Your contributions are greatly appreciated!