Update docs

2 files changed, 64 insertions, 23 deletions

diff --git a/README.md b/README.md
index 00ae2085..eb4b384f 100644
--- a/README.md
+++ b/README.md
@@ -93,21 +93,6 @@ If you're interested in modifying the code:
 * architecture: [doc/architecture.md](doc/architecture.md)
 * style guide, debugging tips, etc.: [doc/hacking.md](doc/hacking.md)
 
-## Neighbors
-
-Many other text-based web browsers exist. Here's some recommendations if you
-want to try more established ones:
-
-* [w3m](https://github.com/tats/w3m) - A text-mode browser, extensible using
-  local-cgi. Also has inline image display and very good table support.
-  Main source of inspiration for Chawan.
-* [elinks](https://github.com/rkd77/elinks) - Has CSS and JavaScript support,
-  and incremental rendering (it's pretty fast.)
-* [lynx](https://lynx.invisible-island.net/) - "THE text-based web browser."
-* [edbrowse](http://edbrowse.org/) - This one looks more like `ed` than
-  `less` or `vi`. Mainly designed for blind users.
-* [browsh](https://www.brow.sh/) - Firefox in your terminal.
-
 ## FAQ
 
 ### I have encountered a bug/technical issue while using Chawan.
@@ -150,13 +135,37 @@ initially intended to (like CSS). Now it is mainly focused on:
 * Simplicity, as much as "modern standards" permit. Chawan has very few external
   dependencies, and favors reduced code size over speed. This lowers the risk
   of supply chain attacks, and helps me understand what my browser is doing.
-* Privacy & security. The default configuration sacrifices usability in favor of
-  privacy on purpose, and unsafe features like JS, cookies, etc. must be enabled
-  separately. The multi-processed design enables effective sandboxing of
-  critical processes.
+* Secure defaults over convenience. Like w3m, extra configuration is
+  needed to enable dangerous features (JS, cookies, etc.) Unlike w3m, we
+  also run buffers in separate, sandboxed processes.
 * Adding the rest of missing w3m features, and improving upon those.
 * Most importantly: having fun in the process :)
 
+## Neighbors
+
+Many other text-based web browsers exist. Here's some recommendations
+(not meant to be an exhaustive list):
+
+* [w3m](https://github.com/tats/w3m) - A text-mode browser, extensible using
+  local-cgi. Also has inline image display and very good table support.
+  Main source of inspiration for Chawan.
+* [elinks](https://github.com/rkd77/elinks) - Has CSS and JavaScript support,
+  and incremental rendering (it's pretty fast.)
+* [links](http://links.twibright.com/) - Precursor of elinks, but it's still
+  being developed. Has a graphical mode.
+* [lynx](https://lynx.invisible-island.net/) - Doesn't need an introduction.
+* [edbrowse](http://edbrowse.org/) - This one looks more like `ed` than
+  `less` or `vi`. Originally designed for blind users.
+* [telescope](https://github.com/telescope-browser/telescope) - A "small
+  internet" (Gemini, Gopher, etc.) browser. Has a very cool UI.
+* [browsh](https://www.brow.sh/) - Firefox in your terminal.
+* [Carbonyl](https://github.com/fathyb/carbonyl) - Chromium in your terminal.
+
+## Relatives
+
+[Ferus](https://github.com/ferus-web/ferus) is a graphical browser
+engine written in Nim that uses Chawan's HTML parser.
+
 ## License
 
 Chawan is dedicated to the public domain. See the UNLICENSE file for details.
diff --git a/doc/image.md b/doc/image.md
index 14f8f124..a0f8766f 100644
--- a/doc/image.md
+++ b/doc/image.md
@@ -23,15 +23,15 @@ In most cases, all you need to do is to set "buffer.images" to true;
 with the default image-mode, Chawan will find the best image display
 method supported by your terminal.
 
-However, there are terminals (such as yaft) that support an image output
-method but do not advertise it (and are therefore left undetected). For
-such terminals, you also have to set "display.image-mode" appropriately.
+If your terminal does not tell Chawan that it can display sixels, you may also
+have to set "display.image-mode" appropriately.  See below for further
+discussion of sixel configuration.
 
 ## Output formats
 
 Supported output formats are:
 
-* The DEC SIXEL format
+* The DEC Sixel format
 * The Kitty terminal graphics protocol
 
 The former is supported because it's ubiquitiously adopted; the latter
@@ -43,6 +43,38 @@ above two anyways.)
 
 Support for hacks such as w3mimgdisplay, ueberzug, etc. is not planned.
 
+### Sixel
+
+Sixel is the most widely supported image format. See <https://arewesixelyet.com>
+to find a terminal that supports it.
+
+Known quirks and implementation details:
+
+* XTerm needs extensive configuration for ideal sixel support. In particular,
+  you will want to set the "decTerminalID", "numColorRegisters",
+  and "maxGraphicSize" attributes. See `man xterm` for details.
+* We assume private color registers are supported. On terminals where they
+  aren't (e.g. SyncTERM or hardware terminals), colors will get messed up with
+  multiple images on screen.
+* We send XTSMGRAPHICS for retrieving the number of color registers; on failure,
+  we fall back to 256. You can override color register count using the
+  `display.sixel-colors` configuration value.
+* For the most efficient sixel display, you will want a cell height that
+  is a multiple of 6. Otherwise, the images will have to be re-coded several
+  times on scroll.
+* Normally, Sixel encoding runs in two passes. On slow computers, you can try
+  setting `display.sixel-colors = 2`, which will skip the first pass.
+* Transparency is currently not supported; you will get strange results with
+  transparent images.
+
+### Kitty
+
+On terminals that support it, Kitty is preferred over Sixel. The Kitty
+protocol has the benefit that it can reuse images we have sent at least once,
+so it is normally more efficient than the former.
+
+To minimize transfer size, we encode images to PNG before displaying them.
+
 ## Input formats
 
 Currently, the supported input formats are: