Closes #100, breaks up the README

4 files changed, 140 insertions, 0 deletions

diff --git a/docs/colorschemes.md b/docs/colorschemes.md
new file mode 100644
index 0000000..430a372
--- /dev/null
+++ b/docs/colorschemes.md
@@ -0,0 +1,12 @@
+# Colorschemes
+
+gotop ships with a few colorschemes which can be set with the `-c` flag followed by the name of one. You can find all the colorschemes in the [colorschemes folder](./colorschemes).
+
+To make a custom colorscheme, check out the [template](./colorschemes/template.go) for instructions and then use [default.json](./colorschemes/default.json) as a starter. Then put the file at `~/.config/gotop/<name>.json` and load it with `gotop -c <name>`. Colorschemes PR's are welcome!
+
+To list all built-in color schemes, call:
+
+```
+gotop --list colorschemes
+```
+
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..f452106
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,12 @@
+# Config file
+
+Most command-line settings can be persisted into a configuration file. The config file is named `gotop.conf` and can be located in several places. The first place gotop will look is in the current directory; after this, the locations depend on the OS and distribution. On Linux using XDG, for instance, the home location of `~/.config/gotop/gotop.conf` is the second location. The last location is a system-wide global location, such as `/etc/gotop/gotop.conf`. The `-h` help command will print out all of the locations, in order. Command-line options override values in any config files, and only the first config file found is loaded.
+
+A configuration file can be created using the `--write-config` command-line argument. This will try to place the config file in the home config directory (the second location), but if it's unable to do so it'll write a file to the current directory.
+
+Config file changes can be made by combining command-line arguments with `--write-config`. For example, to persist the `solarized` theme, call:
+
+```
+gotop -c solarized --write-config
+```
+
diff --git a/docs/devices.md b/docs/devices.md
new file mode 100644
index 0000000..4f9e34c
--- /dev/null
+++ b/docs/devices.md
@@ -0,0 +1,37 @@
+# Device filtering
+
+Some devices have quite a number of data points; on OSX, for instance, there are dozens of temperature readings. These can be filtered through a configuration file.  There is no command-line argument for this filter.
+
+The list will grow, but for now the only device that supports filtering is the temperature widget.  The configuration entry is called `temperature`, and it contains an exact-match list of comma-separated values with no spaces.  To see the list of valid values, run gotop with the `--list devices` command.  Gotop will print out the type of device and the legal values.  For example, on Linux:
+
+```
+$ gotop --list devices
+Temperatures:
+        acpitz
+        nvme_composite
+        nvme_sensor1
+        nvme_sensor2
+        pch_cannonlake
+        coretemp_packageid0
+        coretemp_core0
+        coretemp_core1
+        coretemp_core2
+        coretemp_core3
+        ath10k_hwmon
+```
+You might then add the following line to the config file.  First, find where gotop looks for config files:
+```
+➜  gotop --list paths
+Loadable colorschemes & layouts, and the config file, are searched for, in order:
+/home/ser/workspace/gotop.d/gotop
+/home/ser/.config/gotop
+/etc/xdg/gotop
+
+The log file is in /home/ser/.cache/gotop/errors.log
+```
+So you might use `${HOME}/.config/gotop/gotop.conf`, and add (or modify) this line:
+```
+temperatures=acpitz,coretemp_core0,ath10k_hwmon
+```
+This will cause the temp widget to show only four of the eleven temps.
+
diff --git a/docs/layouts.md b/docs/layouts.md
new file mode 100644
index 0000000..c2f4a8b
--- /dev/null
+++ b/docs/layouts.md
@@ -0,0 +1,79 @@
+# Layouts
+
+gotop can parse and render layouts from a specification file.  The format is
+intentionally simple.  The amount of nesting levels is limited.  Some examples
+are in the `layouts` directory; you can try each of these with, e.g.,
+`gotop --layout-file layouts/procs`.  If you stick your layouts in
+`$XDG_CONFIG_HOME/gotop`, you can reference them on the command line with the
+`-l` argument, e.g. `gotop -l procs`.
+
+The syntax for each widget in a row is:
+```
+(rowspan:)?widget(/weight)?
+```
+and these are separated by spaces.
+
+1. Each line is a row
+2. Empty lines are skipped
+3. Spaces are compressed (so you can do limited visual formatting)
+4. Legal widget names are: cpu, disk, mem, temp, batt, net, procs
+5. Widget names are not case sensitive
+4. The simplest row is a single widget, by name, e.g. `cpu`
+5. **Weights**
+    1. Widgets with no weights have a weight of 1.
+    2. If multiple widgets are put on a row with no weights, they will all have
+       the same width.
+    3. Weights are integers
+    4. A widget will have a width proportional to its weight divided by the
+       total weight count of the row. E.g.,
+
+       ```
+       cpu      net
+       disk/2   mem/4
+       ```
+
+       The first row will have two widgets: the CPU and network widgets; each
+       will be 50% of the total width wide.  The second row will have two
+       widgets: disk and memory; the first will be 2/6 ~= 33% wide, and the
+       second will be 5/7 ~= 67% wide (or, memory will be twice as wide as disk).
+9.  If prefixed by a number and colon, the widget will span that number of
+    rows downward. E.g.
+
+    ```
+    mem   2:cpu
+    net
+    ```
+
+    Here, memory and network will be in the same row as CPU, one over the other,
+    and each half as high as CPU; it'll look like this:
+
+    ```
+     +------+------+
+     | Mem  |      |
+     +------+ CPU  |
+     | Net  |      |
+     +------+------+
+    ```
+     
+10. Negative, 0, or non-integer weights will be recorded as "1".  Same for row
+    spans. 
+11. Unrecognized widget names will cause the application to abort.                          
+12. In rows with multi-row spanning widgets **and** weights, weights in
+    lower rows are ignored.  Put the weight on the widgets in that row, not
+    in later (spanned) rows.
+13. Widgets are filled in top down, left-to-right order.
+14. The larges row span in a row defines the top-level row span; all smaller
+    row spans constitude sub-rows in the row. For example, `cpu mem/3 net/5`
+    means that net/5 will be 5 rows tall overall, and mem will compose 3 of
+    them. If following rows do not have enough widgets to fill the gaps,
+    spacers will be used.
+
+Yes, you're clever enough to break the layout algorithm, but if you try to
+build massive edifices, you're in for disappointment.
+
+To list all built-in color schemes, call:
+
+```
+gotop --list layouts
+```
+