diff options
| -rw-r--r-- | README.md | 199 | ||||
| -rw-r--r-- | doc/architecture.md | 31 | ||||
| -rw-r--r-- | doc/config.md | 2 | ||||
| -rw-r--r-- | doc/troubleshooting.md | 116 |
4 files changed, 186 insertions, 162 deletions
diff --git a/README.md b/README.md index c30e0590..706df706 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Note: a POSIX-compliant operating system is required. 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 1.6.14 or newer, ideally 2.0.4. Versions older than 1.6.14 + * Please use 1.6.14 or newer, ideally 2.0.6. Versions older than 1.6.14 will not work. (You can check your Nim compiler's version using `nim -v`.) 3. Install the following dependencies: @@ -26,8 +26,8 @@ Note: a POSIX-compliant operating system is required. * pkg-config, pkgconf, or similar (must be found as "pkg-config" in your `$PATH`) * (Linux only) libseccomp: <https://github.com/seccomp/libseccomp> - * GNU make. On systems where it is not the default make, install and use - `gmake` in the following steps. + * GNU make. On systems where it is not the default make, use `gmake` + in the following steps. * Recommended: a termcap library. e.g. ncurses comes with one. * TL;DR for Debian: `apt install libcurl4-openssl-dev pkg-config make ncurses-base libseccomp-dev` @@ -47,24 +47,19 @@ $ mancha cha # read the cha(1) man page using `mancha' Currently implemented features are: -* multi-processing (several buffers can be loaded at once) +* multi-processing, incremental loading of documents * multi-charset, double-width aware text display (but no bi-di yet) -* HTML5 support -* CSS-capable layout engine - * flow layout (with floats!), automatic table layout, flexbox layout - (some flex attributes still WIP) -* forms -* incremental loading of documents -* JavaScript based navigation (i.e. programmable keybindings) -* JavaScript support in documents - * some basic DOM manipulation APIs are supported - * disabled by default; enable it at your own risk. -* cookies +* HTML5 support, forms, cookies +* CSS-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) * supports several protocols: HTTP(S), FTP, Gopher, Gemini, Finger, etc. -* can load user-defined protocols/file formats using [local CGI](doc/localcgi.md), - [urimethodmap](doc/urimethodmap.md) and [mailcap](doc/mailcap.md) -* markdown viewer -* man page viewer (like w3mman) +* can [load](doc/localcgi.md) [user-defined](doc/urimethodmap.md) + [protocols](doc/protocols.md)/[file formats](doc/mailcap.md) +* built-in markdown viewer, man page viewer +* WIP sixel/kitty image support (still somewhat limited; progress tracked at + <https://todo.sr.ht/~bptato/chawan/13>) * mouse support * OS-level sandboxing on FreeBSD, OpenBSD and Linux (through Capsicum, pledge and libseccomp) @@ -82,6 +77,7 @@ Currently implemented features are: * urimethodmap: [doc/urimethodmap.md](doc/urimethodmap.md) * local CGI: [doc/localcgi.md](doc/localcgi.md) * protocols: [doc/protocols.md](doc/protocols.md) +* troubleshooting: [doc/troubleshooting.md](doc/troubleshooting.md) ## Neighbors @@ -100,146 +96,49 @@ want to try more established ones: ## FAQ -### I can't select/copy text with my mouse? +### I have encountered a bug/technical issue while using Chawan. -Your options are: - -* Use `v` (and copy with `y`). Drawback: requires keyboard -* Hold down the shift key while selecting. Drawback: can only select text - currently on the screen -* Disable mouse support (`input.use-mouse = false` in config.toml). Drawback: - see above (plus now you can't use the mouse to move on the screen) - -### Why do I get strange/incorrect/ugly colors? - -Chawan's display capabilities depend on what your terminal reports. In -particular: - -* if the `$COLORTERM` variable is not set, then it may fall back to 8-bit or - ANSI colors -* if it does not respond to querying the background color, then Chawan's color - contrast correction will likely malfunction - -You can fix this manually by adjusting the `display.default-background-color`, -`display.default-foreground-color`, and `display.color-mode` variables. See -[doc/config.md](doc/config.md#display) for details. - -### Can I view Markdown files using Chawan? - -Yes; Chawan now has a built-in markdown converter. If you don't like it, you -can always [replace it](doc/mailcap.md) with e.g. pandoc. - -### I set my `$PAGER` to `cha` and now man pages are unreadable. - -Most `man` implementations print formatted manual pages by default, which -Chawan *can* parse if they are passed through standard input. - -Unfortunately, mandoc passes us the formatted document as a *file*, which Chawan -reasonably interprets as plain text without formatting. - -At this point you have two options: - -* `export PAGER='cha -T text/x-ansi'` and see that man suddenly works as - expected. -* `alias man=mancha` and see that man suddenly works better than expected. - -Ideally you should do both, to deal with cases like git help which shells out to -man directly. - -### Where are the keybindings? - -Please run `cha about:chawan` for a list of default keybindings. Users familiar -with *vi*, *vim*, etc. should find these defaults familiar. - -A w3m-like keymap also exists at [bonus/w3m.toml](bonus/w3m.toml). Note that not -every w3m feature is implemented yet, so it's not 100% compatible. - -### How do I view text files with wrapping? - -By default, text files are not auto-wrapped, so viewing plain text files that -were not wrapped properly by the authors is somewhat annoying. - -A workaround is to add this to your [config](doc/config.md#keybindings)'s -`[page]` section: - -```toml -' f' = "pager.externFilterSource('fmt')" -``` - -and then press `<space> f` to view a wrapped version of the current text -file. (This assumes your system has an `fmt` program - if not, `fold -s` may -be an alternative.) - -To always automatically wrap, you can add this to your -[user style](doc/config.md#stylesheets): - -```css -plaintext { white-space: pre-wrap } -``` - -To do the same for HTML and ANSI text, use `plaintext, pre`. - -### Why does `$WEBSITE` look awful? - -Usually, this is because it uses some CSS features that are not yet implemented -in Chawan. The most common offenders are grid and CSS variables. - -There are three ways of dealing with this: - -1. If the website's contents are mostly text, install - [rdrview](https://github.com/eafer/rdrview). Then bind the following command - to a key of your choice in the [config](doc/config.md#keybindings) - (e.g. `<space> r`):<br> - `' r' = "pager.externFilterSource('rdrview -H -u \"$CHA_URL\"')"`<br> - This does not fix the core problem, but will significantly improve your - reading experience anyway. -2. Complain [here](https://todo.sr.ht/~bptato/chawan), and wait until the - problem goes away. -3. Write a patch to fix the problem, and send it - [here](https://lists.sr.ht/~bptato/chawan-devel). - -### `$WEBSITE`'s interactive features don't work! - -Some potential fixes: - -* Logging in to websites requires cookies. Some websites also require cookie - sharing across domains. For security reasons, Chawan does not allow any of - this by default, so you will have to fiddle with siteconf to fix it. See - [doc/config.md#siteconf](doc/config.md#siteconf) for details. -* Set the `referer-from` siteconf value to true; this will cause Chawan to send - a `Referer` header when navigating to other URLs from the target URL. -* Enable JavaScript. If something broke, type M-c M-c to check the browser - console, then follow step 3. of the previous answer.<br> - Warning: remote JavaScript execution is inherently unsafe. Please only enable - JavaScript on websites you trust. +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: -* Written in Nim -* Uses QuickJS for JavaScript execution. (The QuickJS regex engine, libregexp, - is also used for in-document searches.) -* Uses multi-processing provided by POSIX. (No threads.) Each buffer gets - its own process; as a result, buffers can be duplicated by simply forking - their process. File loading is done in yet another process. IPC happens - through UNIX domain sockets. -* Layout, CSS cascading, HTML parsing, etc. are handled by built-in modules, not - external libraries. (However, the HTML parser and the character coding library - are available as separate libraries as well.) -* Uses termcap for basic terminal capability querying, and notcurses-style - terminal queries for detecting "modern" features (like true color). - -For further details, ~~you will have to read the source code~~ please read -[this](doc/architecture.md). +* 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 for JavaScript execution and regex matching. +* Each buffer (page) is isolated in a separate process. File loading is done + through dedicated loader processes. +* termcap for basic terminal capability querying, and terminal queries where + possible. +* The default image decoder currently uses the `stb_image` library. Image codecs + are handled as protocols, so users will be able to add their own codecs (once + I document how it works...) + +For further details, please refer to the [architecture](doc/architecture.md) +document. ### Why write another web browser? -I've found other text-based web browsers insufficient for my needs, so -I thought it'd be a fun excercise to write one by myself, for myself. - -Generally, I'm happy if Chawan works on websites I use frequently. If it -also works on other websites, that's a bonus. +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. +* 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. +* Adding the rest of missing w3m features, and improving upon those. +* Most importantly: having fun in the process :) ## License diff --git a/doc/architecture.md b/doc/architecture.md index afee484b..b6e927e8 100644 --- a/doc/architecture.md +++ b/doc/architecture.md @@ -22,7 +22,7 @@ This document describes some aspects of how Chawan works. ## Module organization -Explanation for the separate directories found in src/: +Explanation for the separate directories found in `src/`: * bindings: bindings for various C libraries. (Not wrappers, just the plain C API as Nim procedure prototypes.) @@ -42,6 +42,15 @@ Explanation for the separate directories found in src/: * types: mainly definitions of data types and things I didn't know where to put. * utils: things I didn't know where to put part 2 +Additionally, "adapters" of various protocols and file formats can be found in +`adapter/`: + +* protocol: includes support for every protocol supported by Chawan. +* format: HTML converters for various text-based file formats. +* img: image decoders and encoders. In general, these just read and output + RGBA data through standard I/O. (This is not very efficient, and therefore + subject to change.) + ## Process model Described as a tree: @@ -214,11 +223,11 @@ cycle collector can break up. A cross-GC cycle collector is obviously out of question; then it would be easier to just replace the entire GC in one of the runtimes. -But we don't replace anything. Instead, we hook into the QuickJS cycle -collector (through a custom patch). Every time a JS companion object of a Nim -object would be freed, we first check if the Nim object still has references -from Nim, and if yes, prevent the JS object from being freed by "moving" a -reference to the JS object (i.e. unref Nim, ref JS). +So instead, we hook into the QuickJS cycle collector (through a custom +patch). Every time a JS companion object of a Nim object would be freed, we +first check if the Nim object still has references from Nim, and if yes, prevent +the JS object from being freed by "moving" a reference to the JS object +(i.e. unref Nim, ref JS). Then, if we want to pass the object to JS again, we add no references to the JS object, only to the Nim object. By this, we "moved" the reference back to JS. @@ -270,7 +279,7 @@ works OK, but is missing features like variables. Cascading is slow, though it could be slower. Chawan has style caching, so re-styles are normally very fast. Also, a hash map is used for reducing initial -style calculation times. However, we don't have a bloom filter yet. +style calculation times. However, we don't have a Bloom filter yet. ## Layout @@ -279,10 +288,10 @@ Layout can be found in the layout/ module. It has some problems: * CSS was designed for pixel-based displays, not for character-based ones. So we - have to round a lot, and sometimes this goes wrong. -* In the past years, websites have finally started using grid, and we don't have - it, so those websites look very ugly. -* Even what we do have has plenty of bugs. (Sad.) + have to round a lot, and sometimes this goes wrong. (This is mostly solved by + some basic heuristics inside the layout engine.) +* Some (now) commonly used features like grid are not implemented, so websites + using those look ugly. * It's slow on large documents, because we don't have partial layouting capabilities. diff --git a/doc/config.md b/doc/config.md index 80e15215..e1b359f5 100644 --- a/doc/config.md +++ b/doc/config.md @@ -135,7 +135,7 @@ enable JavaScript with `[[siteconf]]` instead of using this setting.</td> <td>images</td> <td>boolean</td> <td>Enable/disable experimental image support.<br> -Defaults to false, but this may change in the future.</td> +Defaults to false.</td> </tr> <tr> diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md new file mode 100644 index 00000000..eea64aff --- /dev/null +++ b/doc/troubleshooting.md @@ -0,0 +1,116 @@ +# Troubleshooting Chawan + +This document lists common problems you may run into when using Chawan. + +## I can't select/copy text with my mouse? + +Your options are: + +* Use `v` (and copy with `y`). Drawback: requires keyboard +* Hold down the shift key while selecting. Drawback: can only select text + currently on the screen +* Disable mouse support (`input.use-mouse = false` in config.toml). Drawback: + see above (plus now you can't use the mouse to move on the screen) + +## Why do I get strange/incorrect/ugly colors? + +Chawan's display capabilities depend on what your terminal reports. In +particular: + +* if the `$COLORTERM` variable is not set, then it may fall back to 8-bit or + ANSI colors +* if it does not respond to querying the background color, then Chawan's color + contrast correction will likely malfunction + +You can fix this manually by exporting `COLORTERM=truecolor` and +`display.default-background-color`/`display.default-foreground-color` +variables. See [config.md](config.md#display) for details. + +## Can I view Markdown files using Chawan? + +Yes; Chawan now has a built-in markdown converter. If you don't like it, you +can always [replace it](mailcap.md) with e.g. pandoc. + +## I set my `$PAGER` to `cha` and now man pages are unreadable. + +Most `man` implementations print formatted manual pages by default, which +Chawan *can* parse if they are passed through standard input. + +Unfortunately, mandoc passes us the formatted document as a *file*, which Chawan +reasonably interprets as plain text without formatting. + +At this point you have two options: + +* `export PAGER='cha -T text/x-ansi'` and see that man suddenly works as + expected. +* `alias man=mancha` and see that man suddenly works better than expected. + +Ideally you should do both, to deal with cases like git help which shells out to +man directly. + +## Where are the keybindings? + +Please run `cha about:chawan` for a list of default keybindings. Users familiar +with *vi*, *vim*, etc. should find these defaults familiar. + +A w3m-like keymap also exists at [bonus/w3m.toml](bonus/w3m.toml). Note that not +every w3m feature is implemented yet, so it's not 100% compatible. + +## How do I view text files with wrapping? + +By default, text files are not auto-wrapped, so viewing plain text files that +were not wrapped properly by the authors is somewhat annoying. + +A workaround is to add this to your [config](config.md#keybindings)'s +`[page]` section: + +```toml +' f' = "pager.externFilterSource('fmt')" +``` + +and then press `<space> f` to view a wrapped version of the current text +file. (This assumes your system has an `fmt` program - if not, `fold -s` may +be an alternative.) + +To always automatically wrap, you can add this to your +[user style](config.md#stylesheets): + +```css +plaintext { white-space: pre-wrap } +``` + +To do the same for HTML and ANSI text, use `plaintext, pre`. + +## Why does `$WEBSITE` look awful? + +Usually, this is because it uses some CSS features that are not yet implemented +in Chawan. The most common offenders are grid and CSS variables. + +There are three ways of dealing with this: + +1. If the website's contents are mostly text, install + [rdrview](https://github.com/eafer/rdrview). Then bind the following command + to a key of your choice in the [config](config.md#keybindings) + (e.g. `<space> r`):<br> + `' r' = "pager.externFilterSource('rdrview -H -u \"$CHA_URL\"')"`<br> + This does not fix the core problem, but will significantly improve your + reading experience anyway. +2. Complain [here](https://todo.sr.ht/~bptato/chawan), and wait until the + problem goes away. +3. Write a patch to fix the problem, and send it + [here](https://lists.sr.ht/~bptato/chawan-devel). + +## `$WEBSITE`'s interactive features don't work! + +Some potential fixes: + +* Logging in to websites requires cookies. Some websites also require cookie + sharing across domains. For security reasons, Chawan does not allow any of + this by default, so you will have to fiddle with siteconf to fix it. See + [config.md#siteconf](config.md#siteconf) for details. +* Set the `referer-from` siteconf value to true; this will cause Chawan to send + a `Referer` header when navigating to other URLs from the target URL. +* Enable JavaScript. If something broke, type M-c M-c to check the browser + console, then follow step 3. of the previous answer.<br> + Warning: remote JavaScript execution is inherently unsafe. Please only enable + JavaScript on websites you trust. |