Doc tweaks

Manual.md

@@ -2,28 +2,21 @@
 
 ## Introduction
 
-MapEditr is a command-line tool for editing Minetest worlds, specifically
+MapEditr is a command-line tool for editing Minetest worlds. Note that MapEditr
-Minetest maps. Note that MapEditr is not a mod or plugin; it is a separate
+is not a mod or plugin; it is a separate program which operates independently
-program which operates independently of Minetest.
+of Minetest.
 
-Minetest *worlds* are stored in the `worlds` folder within Minetest's
+MapEditr reads and edits *map databases*, usually a file named `map.sqlite`
-installation directory. Each world is a folder containing a *map database*,
+within each Minetest world directory. As such, the terms "world" and "map" may
-usually named `map.sqlite`, among other files. The map database contains the
+be used interchangeably.
-physical layout of that world, including all nodes (blocks) and objects (mobs,
-etc.). This file is what MapEditr reads and edits.
 
-Minetest stores map data in *mapblocks*. A single map block is a cubical,
+For most commands to work, the areas of the map to be read/modified must
-16x16x16 node area of the map. The lower southwestern corner of a mapblock
+already be generated. This can be done by either exploring the area in-game,
-(towards -X, -Y, -Z) is always at coordinates divisible by 16, e.g.
+or by using Minetest's built-in `/emergeblocks` command.
-(0, 16, -48) or the like.
 
-For most commands to work, the mapblocks to be read and modified must already
+MapEditr supports all maps created since Minetest version 0.4.2-rc1, released
-be generated within Minetest. This can be achieved by either exploring the area
+July 2012. Any unsupported areas of the map will be skipped (TODO). Note that
-in-game, or by using Minetest's built-in `/emergeblocks` command.
+only SQLite format maps are currently supported.
-
-MapEditr supports map format versions 25 through 28, meaning all worlds
-created since Minetest version 0.4.2-rc1 (released July 2012) should be
-supported. Unsupported mapblocks will be skipped (TODO).
 
 ## General usage
 
@@ -32,10 +25,9 @@ supported. Unsupported mapblocks will be skipped (TODO).
 Arguments:
 
 - `-h`: Show a help message and exit.
-- `<map>`: Path to the Minetest world to edit; this can be either a world
+- `<map>`: Path to the Minetest world/map to edit; this can be either a world
-directory or a `map.sqlite` file. Note that only worlds with SQLite map
+directory or a `map.sqlite` file within a world folder. This file will be
-databases are currently supported. This file will be modified, so *always* shut
+modified, so *always* shut down the game/server before executing any command.
-down the game/server before executing the command.
 - `<subcommand>`: Command to execute. See "Commands" section below.
 
 ### Common command arguments
@@ -57,6 +49,21 @@ WorldEdit `//fixlight` command.
 
 ## Commands
 
+### clone
+
+Usage: `clone --p1 x y z --p2 x y z --offset x y z`
+
+Clone (copy) the given area to a new location.
+
+Arguments:
+
+- `--p1, --p2`: Area to copy from.
+- `--offset`: Offset to shift the area by. For example, to copy an area 50
+nodes upward (positive Y direction), use `--offset 0 50 0`.
+
+This command copies nodes, param1, param2, and metadata. Nothing will be copied
+into mapblocks that are not yet generated.
+
 ### deleteblocks
 
 Usage: `deleteblocks --p1 x y z --p2 x y z [--invert]`
@@ -90,6 +97,19 @@ name is specified, only items with that name will be deleted.
 be deleted everywhere.
 - `--invert`: Delete objects *outside* the given area.
 
+### deletetimers
+
+Usage: `deletetimers [--node <node>] [--p1 x y z] [--p2 x y z] [--invert]`
+
+Delete node timers of a certain node and/or within a certain area.
+
+Arguments:
+
+- `--node`: Name of node to modify. If not specified, the node timers of all
+nodes will be deleted.
+- `--p1, --p2`: Area in which to delete node timers.
+- `--invert`: Only delete node timers *outside* the given area.
+
 ### fill
 
 Usage: `fill --p1 x y z --p2 x y z [--invert] <new_node>`
@@ -105,38 +125,29 @@ Arguments:
 - `--p1, --p2`: Area to fill.
 - `--invert`: Fill everything *outside* the given area.
 
-### clone
-
-Usage: `clone --p1 x y z --p2 x y z --offset x y z`
-
-Clone (copy) the given area to a new location.
-
-Arguments:
-
-- `--p1, --p2`: Area to copy from.
-- `--offset`: Offset to shift the area by. For example, to copy an area 50
-nodes upward (positive Y direction), use `--offset 0 50 0`.
-
-This command copies nodes, param1, param2, and metadata. Nothing will be copied
-into mapblocks that are not yet generated.
-
 ### overlay
 
-Usage: `overlay [--p1 x y z] [--p2 x y z] [--invert] [--offset x y z] <input_map>`
+Usage: `overlay <input_map> [--p1 x y z] [--p2 x y z] [--invert] [--offset x y z]`
 
-Copy part or all of an input map into the main map.
+Copy part or all of a source map into the main map.
 
 Arguments:
 
-- `input_map`: Path to input map file. This will not be modified.
+- `input_map`: Path to source map/world. This will not be modified.
 - `--p1, --p2`: Area to copy from. If not specified, MapEditr will try to
 copy everything from the input map file.
 - `--invert`: If present, copy everything *outside* the given area.
 - `--offset`: Offset to move nodes by when copying; default is no offset.
 Currently, an offset cannot be used with an inverted selection.
 
-This command will always copy nodes, param1 and param2, and metadata. If no
+This command will always copy nodes, param1, param2, and metadata. If no
-offset is used, entities and node timers may also be copied.
+offset is used, objects/entities and node timers may also be copied.
+
+To ensure that all data is copied, make sure the edges of the selection are
+generated in the destination map, or the entire selection if an offset is used.
+
+**Tip:** Overlay will be significantly faster if no offset is used, as
+mapblocks can be copied verbatim.
 
 ### replacenodes
 
@@ -235,15 +246,3 @@ Arguments:
 - **`--invert`**: Only search for nodes *outside* the given area.
 
 **Tip:** To only delete metadata without replacing the nodes, use the `--deletemeta` flag, and make `replaceitem` the same as `searchitem`.
-
-### `deletetimers`
-
-**Usage:** `deletetimers [--searchnode <searchnode>] [--p1 x y z] [--p2 x y z] [--invert]`
-
-Delete node timers of a certain node and/or within a certain area.
-
-Arguments:
-
-- **`--searchnode`**: Name of node to search for. If not specified, the node timers of all nodes will be deleted.
-- **`--p1, --p2`**: Area in which to delete node timers. Required if `searchnode` is not specified.
-- **`--invert`**: Only delete node timers *outside* the given area.

README.md

@@ -9,19 +9,16 @@ operations that would be impractical to do using WorldEdit. Since it is mainly
 optimized for speed, MapEditr is not as full-featured as in-game world editors
 such as WorldEdit.
 
-MapEditr is originally based on [MapEdit][2], but rewritten in Rust,
+MapEditr is originally based on [MapEdit][2], but rewritten in Rust, hence the
-hence the added "r". Switching to a compiled language will make MapEditr more
+added "r". Switching to a compiled language will make MapEditr more robust and
-robust and easier to maintain in the future.
+easier to maintain in the future.
 
 [1]: https://github.com/Uberi/Minetest-WorldEdit
 [2]: https://github.com/random-geek/MapEdit
 
 ## Installation
 
-TODO: This section is vague.
+TODO: Pre-built binaries
-
-Pre-built binaries are available on the Releases page. This is the easiest way
-to get MapEditr.
 
 To compile from source, you must have Rust installed first, which can be
 downloaded from [here][3]. Then, in the MapEditr directory, run: