readme: revise

README.md

@@ -1,62 +1,57 @@
 ## callisto - standalone scripting platform for Lua 5.4
 
-Callisto extends Lua 5.4's standard library by adding new libraries and
-facilities to the language. It includes a file system library to manage
-and manipulate files, a process library to find active processes and
-manipulate signals, and a JSON manipulation library (lua-cjson) *among
-many more*.
+Callisto extends Lua 5.4's standard library by adding new modules and
+facilities to the interpreter. It includes a file system library to
+manage and manipulate files and directories, a process library to find
+active processes and manipulate signals, and a JSON manipulation
+library (lua-cjson) *among many more*.
 
 It is a standalone interpreter designed for people using Lua as a
-general scripting language, instead of using it embedded into another
-application (what Lua was designed for).
-
-Before I made Callisto, I had to rely on luaposix for basic file system
-manipulation and occasionally luasocket for HTTP plus lua-cjson for JSON
-parsing.
-
-luaposix provides most of the necessary functions, but is generally
-aimed towards people who already know how to use the POSIX APIs in C.
+general scripting language, rather than using it embedded into another
+program, which is what Lua was designed for. Perhaps you could think
+of it as a replacement for Python.
 
 First and foremost, Callisto tries to be:
- - an all-in-one zero-dependencies library for Lua that includes
-   most features people would need, out of the box
- - a library that works and integrates well with Lua and its
-   standard library, and is easy to use for those who have no
-   experience with C
+ - a runtime environment for Lua that includes most features people
+   would need out of the box, all in one executable with zero
+   dependencies
+ - a library that works well and integrates well with the Lua language
+   and its standard library, and is easy to use for those who have no
+   prior experience with C
 
 Callisto relies on APIs specified in the POSIX specification;
-therefore it does not support operating systems that do not
-implement these APIs (like Microsoft Windows), only ones that
-do (like Linux, macOS, and the BSDs).
+therefore it cannot be used on operating systems that are not
+POSIX-compliant (like Microsoft Windows).
 
-## Dependencies
+## portability
 
-To build Callisto, you'll need nothing but a C compiler and `ar`.
-The default C compiler is *cc* which is usually a symbolic link
-to your system's default C compiler. This should be gcc on Linux,
-and clang on most of the BSDs. If *cc* doesn't exist on your system,
-override it by adding `CC=compiler` to make's command like
-(replace `compiler` with the name or path to your C compiler)
+To build Callisto, all you need is a C99 compiler. The configure
+script will check for the presence of various compilers before
+building, to decide which one to use.
+The compilers checked are clang, followed by cc, followed by gcc. If
+you have a compiler at a custom path that you would like to use over
+the system C compiler, just pass `-c /path/to/compiler` to the
+configure script before you build. The compiler must support gcc-like
+command line arguments.
 
-### Portability
-
-**Callisto has zero runtime dependencies**, unless you built it with
-support for GNU libreadline.* Lua 5.4 is statically linked in.
-This means that the same binary will likely work across different Linux
-distributions/versions. The only strictly required library is libc
-which is available on all systems.
+Callisto has zero runtime dependencies, unless you built it with
+support for GNU libreadline*. Lua 5.4 is statically linked in. This
+means that the same binary will work across different Linux
+distributions.
 
 *libreadline support can be enabled at build time, but is disabled by
 default. To force building with libreadline support, pass the
 `-wreadline` flag to the configure script.
 
-## Installation
+## installation
 
-Callisto is distributed as source-only, but it's not hard to compile.
+Callisto is distributed as source-only, but it's very easy to build it
+yourself. Just make sure you have a compiler such as gcc installed, as
+well as git for downloading the source code and make for compiling.
 
-First, get the source code using one of the tarballs found in
-the [Releases](https://github.com/jtbx/callisto/releases) page.
-Untar it then enter the directory with Callisto's source code.
+First, obtain a copy of the source code using the following command:
+
+    git clone https://github.com/jtbx/callisto
 
 After that, run
 
@@ -65,8 +60,9 @@ After that, run
 
 to compile Callisto and all its dependencies.
 
-To install it, run `make install` as the root user in the source code directory
-to install Callisto and its shared library.
+To install it, run `make install` as the root user in the source code
+directory. If you choose not to install it, you can still invoke it in
+the current directory.
 
 ### Arch Linux
 
@@ -80,22 +76,27 @@ If you use Nix, you can use the flake:
 
     nix profile install github:jtbx/callisto
 
-## Usage
+## usage
 
-The standalone Callisto interpreter is called `csto`. Running it
-will start a REPL so you can execute chunks of code interactively.
+The standalone Callisto interpreter is called `csto`. This is the main
+way to run Lua programs using the Callisto libraries. Running it
+without arguments will start a read-eval-print loop so you can execute
+chunks of code interactively.
 
 csto works just like the standalone Lua 5.4 interpreter. To execute
-a file, run `csto file` where *file* is the name of the file containing
-code that you want to run. Alternatively, you can put `#!/usr/bin/env csto`
-at the top of your script, run `chmod +x` on it, and then you can run the
-script as if it was a standalone executable, for example `./yourscript.lua`.
+code in a file, run `csto file` where *file* is the name of the file
+containing code you want to run.
 
-## Documentation
+Alternatively, put `#!/usr/bin/env csto` at the top of your script,
+make it executable with `chmod +x`, and then you can run the script as
+if it was a standalone executable, for example `./script.lua`.
 
-Docs can be found here:
+## documentation
+
+Library documentation can be found here:
 https://jtbx.github.io/callisto/doc
 
-## Contributing
+## contributing
 
-Pop me an email with your patch at jtbx@disroot.org or open a Github pull request.
+Drop me an email with your patch at jtbx@disroot.org or open a Github
+pull request. You can optionally read the style.md document :)