diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/architecture.md | 31 | ||||
| -rw-r--r-- | doc/config.md | 2 | ||||
| -rw-r--r-- | doc/troubleshooting.md | 116 |
3 files changed, 137 insertions, 12 deletions
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. |