aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorbptato <nincsnevem662@gmail.com>2025-05-08 22:39:02 +0200
committerbptato <nincsnevem662@gmail.com>2025-05-08 22:52:56 +0200
commit9422ea9bb0bc644560fad510f54c092d8157caa5 (patch)
tree531f2d19c31450177d29010da9fe759d351ce4de
parentfff5a2e3c8a9543b11b3dddfb0fb3f0b39a13589 (diff)
downloadchawan-9422ea9bb0bc644560fad510f54c092d8157caa5.tar.gz
Update readme
If anybody is interested in turning the old neighbors section into an awesome-tui-browsers list, feel free to do so.
-rw-r--r--README.md159
1 files changed, 50 insertions, 109 deletions
diff --git a/README.md b/README.md
index 99eecfd9..293ef0d4 100644
--- a/README.md
+++ b/README.md
@@ -1,37 +1,35 @@
-# Chawan - a web browser for your terminal
+# Chawan
-[Project page](https://sr.ht/~bptato/chawan)
+[Chawan](https://sr.ht/~bptato/chawan) is a TUI web (and (S)FTP, Gopher,
+Gemini, ...) browser with CSS, inline image and JavaScript support.
-![Screenshot of Chawan displaying its SourceHut page](doc/showcase.png)
-
-## What is this?
-
-A text-mode web browser. It displays websites in your terminal and allows
-you to navigate on them.
+It uses its own minimal browser engine developed from scratch, which can
+display many websites in a manner similar to major graphical browsers.
It can also be used as a terminal pager.
+![Screenshot of Chawan displaying its SourceHut page](doc/showcase.png)
+
## Compiling
-Note: a POSIX-compliant operating system is required.
+A Unix-like operating system (Linux, \*BSD, Haiku, macOS, ...) is
+assumed. On Windows you have to use WSL.
1. Clone the Chawan repository:
`git clone https://git.sr.ht/~bptato/chawan && cd chawan`
2. Install the Nim compiler: <https://nim-lang.org/install.html>
- * Please use 2.0.0 or newer, ideally 2.2.2. (Type `nim -v` to
- check your Nim compiler's version.)
- * If you are using a 32-bit system: `export CFLAGS=-fpermissive`
- before compiling, or (preferably) use a nightly build of the
- Nim compiler.
+ * Please use 2.0.0 or newer, ideally 2.2.2. (`nim -v` displays
+ your Nim compiler's version.)
+ * If you are using a 32-bit system, you probably need 2.2 or
+ newer. 2.0 may still work if you `export CFLAGS=-fpermissive`.
3. Install the following dependencies:
* [OpenSSL](https://www.openssl.org/) (or
[LibreSSL](https://www.libressl.org/))
* [libssh2](https://libssh2.org/)
* [brotli](https://github.com/google/brotli)
- * pkg-config, pkgconf, or similar (must be found as "pkg-config" in your
- `$PATH`)
- * GNU make
- * TL;DR for Debian:
+ * pkg-config
+ * GNU make (gmake on non-GNU systems)
+ * Quick copy-paste for Debian:
`apt install libssh2-1-dev libssl-dev libbrotli-dev pkg-config make`
4. Run `make` (without arguments).
5. Install using `make install` (e.g. `sudo make install`).
@@ -46,8 +44,7 @@ $ mancha cha # read the cha(1) man page using `mancha'
## Packages
-Alternatively, you can install Chawan from packages maintained by
-volunteers:
+You can also install Chawan from packages maintained by volunteers:
* AUR: <https://aur.archlinux.org/packages/chawan-git>
* NixOS: <https://search.nixos.org/packages?show=chawan>
@@ -58,28 +55,40 @@ volunteers:
Currently implemented features are:
* multi-processing, incremental loading of documents
-* multi-charset, double-width aware text display (but no bi-di yet)
-* HTML5 support, forms, cookies
+* HTML5 support with various encodings (UTF-8, Shift_JIS, GBK, ...),
+ forms, cookies
* [CSS](doc/css.md)-based layout engine: supports flow layout, table
- layout, flexbox layout
-* user-programmable keybindings (defaults are vi(m)-like)
-* basic JavaScript support in documents (disabled by default for security
- reasons)
-* inline image support with sixel/kitty protocols (disabled by default;
- see [doc/image.md](doc/image.md) on how to enable)
-* supports several [protocols](doc/protocols.md): HTTP(S), FTP, Gopher, Gemini,
- Finger, etc.
-* [user-defined](doc/urimethodmap.md) protocols and
+ layout, flexbox layout, double-width characters (CJK)
+* user-programmable keybindings (defaults are vi(m)-like), mouse support
+* JavaScript support in documents (disabled by default)
+* inline image support with [Sixel](https://en.wikipedia.org/wiki/Sixel) or
+ [Kitty protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/)
+ (disabled by default; see [doc/image.md](doc/image.md) on how to
+ enable)
+* supports several network [protocols](doc/protocols.md): HTTP(S),
+ (S)FTP, Gopher, Gemini, Finger, Spartan
+* markdown viewer (`cha file.md`), man page viewer (`mancha`)
+* [user-defined protocols](doc/urimethodmap.md) and
[file formats](doc/mailcap.md)
-* markdown viewer, man page viewer
-* mouse support
* syscall filter based sandboxing on FreeBSD, OpenBSD and Linux (through
capsicum, pledge and seccomp-bpf)
-* bookmarks
+* bookmarks, history
...with a lot more [planned](todo).
-## Documentation
+## Bugs, technical issues, etc.
+
+First, check the [troubleshooting](doc/troubleshooting.md) document.
+If it doesn't help, [open a ticket](https://todo.sr.ht/~bptato/chawan).
+
+When using the ticket tracker, please make sure your tickets are valid
+markdown, or they become unreadable on the web interface.
+
+If you want to send plain text e-mails not formatted as markdown,
+use the [mailing list](mailto:~bptato/chawan-devel@lists.sr.ht) instead.
+This is also where you can send patches.
+
+## Documentation index
Chawan's documentation is available as man pages (`man cha`) and as
Markdown files.
@@ -103,79 +112,11 @@ 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)
-## FAQ
-
-### I have encountered a bug/technical issue while using Chawan.
-
-Please check our [troubleshooting](doc/troubleshooting.md) document. If this
-does not help, please [open a ticket](https://todo.sr.ht/~bptato/chawan)
-or post to the [mailing list](mailto:~bptato/chawan-devel@lists.sr.ht).
-
-### I'm interested in the technical details of Chawan.
-
-Here's some:
-
-* The browser engine (HTML parsing, rendering, etc.) has been developed
- from scratch in the memory-safe Nim programming language. Some of these
- modules are now also available as separate libraries.
-* Uses [QuickJS-NG](https://github.com/quickjs-ng/quickjs) for JavaScript
- execution and regex matching.
-* Each buffer (page) is isolated in a separate process. File loading is done
- through dedicated loader processes.
-* Uses terminal queries for terminal capability discovery.
-* The default image decoder (PNG, JPEG, GIF, BMP) uses
- [stb_image](https://github.com/nothings/stb), WebP images are
- decoded using [JebP](https://github.com/matanui159/jebp), and SVG is
- decoded using [NanoSVG](https://github.com/memononen/nanosvg). Image
- codecs are handled as protocols, so users can add their own codecs
- (with urimethodmap).
-
-For further details, please refer to the [architecture](doc/architecture.md)
-document.
-
-### Why write another web browser?
-
-w3m is close to my ideal browser, but its architecture leaves a lot to be
-desired. So initially I just wanted a simple w3m clone with a more maintainable
-code base.
-
-The project has evolved a lot since then, even including things I had not
-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.
-* 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://sr.ht/~rkta/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.
- The oldest web browser still in active development.
-* [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, Finger) browser. Has a very cool UI.
-* [offpunk](https://sr.ht/~lioploum/offpunk/) - An offline-first browser
- for Web, Gemini, Gopher, Spartan. Separates "downloading" from "browsing".
-* [browsh](https://www.brow.sh/) - Firefox in your terminal.
-* [Carbonyl](https://github.com/fathyb/carbonyl) - Chromium in your terminal.
-
## Relatives
+[w3m](https://sr.ht/~rkta/w3m) has been the main inspiration for Chawan;
+although the two do not share code, the UI and feature set is similar.
+
[Ferus](https://github.com/ferus-web/ferus) is a separate graphical browser
engine written in Nim, which uses Chawan's HTML parser.
@@ -183,6 +124,6 @@ engine written in Nim, which uses Chawan's HTML parser.
Chawan is dedicated to the public domain. See the UNLICENSE file for details.
-Chawan also includes and depends on several other libraries. For further
-details, check the <about:license> page in Chawan, or read the same document
-[here](res/license.md).
+Chawan also includes and depends on several permissively licensed libraries.
+For further details, check the <about:license> page in Chawan, or read
+the same document [here](res/license.md).