doc: update manpages

1 files changed, 136 insertions, 0 deletions

diff --git a/doc/cha-troubleshooting.5 b/doc/cha-troubleshooting.5
new file mode 100644
index 00000000..8f205664
--- /dev/null
+++ b/doc/cha-troubleshooting.5
@@ -0,0 +1,136 @@
+.\" Automatically generated by Pandoc 3.3
+.\"
+.TH "cha\-troubleshooting" "5" "" "" "Troubleshooting Chawan"
+.SH Troubleshooting Chawan
+This document lists common problems you may run into when using Chawan.
+.SS I can\[cq]t select/copy text with my mouse?
+Your options are:
+.IP \[bu] 2
+Use \f[CR]v\f[R] (and copy with \f[CR]y\f[R]).
+Drawback: requires keyboard
+.IP \[bu] 2
+Hold down the shift key while selecting.
+Drawback: can only select text currently on the screen
+.IP \[bu] 2
+Disable mouse support (\f[CR]input.use\-mouse = false\f[R] in
+config.toml).
+Drawback: see above (plus now you can\[cq]t use the mouse to move on the
+screen)
+.SS Why do I get strange/incorrect/ugly colors?
+Chawan\[cq]s display capabilities depend on what your terminal reports.
+In particular:
+.IP \[bu] 2
+if the \f[CR]$COLORTERM\f[R] variable is not set, then it may fall back
+to 8\-bit or ANSI colors
+.IP \[bu] 2
+if it does not respond to querying the background color, then
+Chawan\[cq]s color contrast correction will likely malfunction
+.PP
+You can fix this manually by exporting \f[CR]COLORTERM=truecolor\f[R]
+and
+\f[CR]display.default\-background\-color\f[R]/\f[CR]display.default\-foreground\-color\f[R]
+variables.
+See config.md for details.
+.SS Can I view Markdown files using Chawan?
+Yes; Chawan now has a built\-in markdown converter.
+If you don\[cq]t like it, you can always replace it with e.g.\ pandoc.
+.SS I set my \f[CR]$PAGER\f[R] to \f[CR]cha\f[R] and now man pages are unreadable.
+Most \f[CR]man\f[R] implementations print formatted manual pages by
+default, which Chawan \f[I]can\f[R] parse if they are passed through
+standard input.
+.PP
+Unfortunately, mandoc passes us the formatted document as a
+\f[I]file\f[R], which Chawan reasonably interprets as plain text without
+formatting.
+.PP
+At this point you have two options:
+.IP \[bu] 2
+\f[CR]export PAGER=\[aq]cha \-T text/x\-ansi\[aq]\f[R] and see that man
+suddenly works as expected.
+.IP \[bu] 2
+\f[CR]alias man=mancha\f[R] and see that man suddenly works better than
+expected.
+.PP
+Ideally you should do both, to deal with cases like git help which
+shells out to man directly.
+.SS Where are the keybindings?
+Please run \f[CR]cha about:chawan\f[R] for a list of default
+keybindings.
+Users familiar with \f[I]vi\f[R], \f[I]vim\f[R], etc.
+should find these defaults familiar.
+.PP
+A w3m\-like keymap also exists at bonus/w3m.toml.
+Note that not every w3m feature is implemented yet, so it\[cq]s not 100%
+compatible.
+.SS 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.
+.PP
+A workaround is to add this to your config\[cq]s \f[CR][page]\f[R]
+section:
+.IP
+.EX
+\[aq] f\[aq] = \[dq]pager.externFilterSource(\[aq]fmt\[aq])\[dq]
+.EE
+.PP
+and then press \f[CR]<space> f\f[R] to view a wrapped version of the
+current text file.
+(This assumes your system has an \f[CR]fmt\f[R] program \- if not,
+\f[CR]fold \-s\f[R] may be an alternative.)
+.PP
+To always automatically wrap, you can add this to your user style:
+.IP
+.EX
+plaintext { \f[B]white\-space\f[R]: pre\-wrap }
+.EE
+.PP
+To do the same for HTML and ANSI text, use \f[CR]plaintext, pre\f[R].
+.SS Why does \f[CR]$WEBSITE\f[R] 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.
+.PP
+There are three ways of dealing with this:
+.IP "1." 3
+If the website\[cq]s contents are mostly text, install \c
+.UR https://github.com/eafer/rdrview
+rdrview
+.UE \c
+\&.
+Then bind the following command to a key of your choice in the config
+(e.g.\ \f[CR]<space> r\f[R]):
+\f[CR]\[aq] r\[aq] = \[dq]pager.externFilterSource(\[aq]rdrview \-H \-u \[dq]$CHA_URL\[dq]\[aq])\[dq]\f[R]
+This does not fix the core problem, but will significantly improve your
+reading experience anyway.
+.IP "2." 3
+Complain \c
+.UR https://todo.sr.ht/~bptato/chawan
+here
+.UE \c
+, and wait until the problem goes away.
+.IP "3." 3
+Write a patch to fix the problem, and send it \c
+.UR https://lists.sr.ht/~bptato/chawan-devel
+here
+.UE \c
+\&.
+.SS \f[CR]$WEBSITE\f[R]\[cq]s interactive features don\[cq]t work!
+Some potential fixes:
+.IP \[bu] 2
+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 for details.
+.IP \[bu] 2
+Set the \f[CR]referer\-from\f[R] siteconf value to true; this will cause
+Chawan to send a \f[CR]Referer\f[R] header when navigating to other URLs
+from the target URL.
+.IP \[bu] 2
+Enable JavaScript.
+If something broke, type M\-c M\-c to check the browser console, then
+follow step 3.
+of the previous answer.
+Warning: remote JavaScript execution is inherently unsafe.
+Please only enable JavaScript on websites you trust.