From 8292d21bc9c786e5e4cb2ef5531b29d0858a8b7e Mon Sep 17 00:00:00 2001 From: bptato Date: Sat, 19 Nov 2022 15:02:40 +0100 Subject: Update docs --- doc/config.md | 159 ++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 89 insertions(+), 70 deletions(-) (limited to 'doc/config.md') diff --git a/doc/config.md b/doc/config.md index b076de5a..bfb1ee7c 100644 --- a/doc/config.md +++ b/doc/config.md @@ -1,10 +1,11 @@ # Configuration -Currently keybindings and a user stylesheet can be configured. The -configuration format for chawan is toml. +Chawan supports custom keybindings and user stylesheets, defined in a toml +configuration file. Chawan will look for a config file in the ~/.config/chawan/ directory called -`config.toml`. For an example see the default configuration in the res/ folder. +`config.toml`. See the default configuration in the res/ folder for the default +configuration. A list of configurable options follows. @@ -16,7 +17,10 @@ Following is a list of general options:
**Name****Value****Function** -
double-width-ambiguousbooleanAssume the terminal displays characters in the East Asian Ambiguous category as double-width characters +
double-width-ambiguousboolean +Assume the terminal displays characters in the East Asian Ambiguous +category as double-width characters. If you don't know what this means, you +probably won't need to enable it.
## Display @@ -27,7 +31,9 @@ Following is a list of display options:
**Name****Value****Function** -
mark-colorcolorSet the marker's color. Valid options are "black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "terminal". +
mark-colorcolorSet the marker's color. Valid options are +"black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", +"terminal".
## Stylesheets @@ -63,80 +69,93 @@ escape to the keybinding respectively (essentially making `M-` the same as (Note: it is highly recommended to use single quotes here; escaping can get quite ugly with double quotes.) -```Example: -'C-M-j' = 'CHANGE_LOCATION' # change URL when Control, Escape and j are pressed -'gg' = 'CURSOR_FIRST_LINE' # go to the first line of the page when g is pressed twice +```Examples: +'C-M-j' = 'pager.changeLocation()' # change URL when Control, Escape and j are pressed +'gg' = 'pager.cursorFirstLine()' # go to the first line of the page when g is pressed twice ``` +An action is a JavaScript function called by chawan every time the keybinding +is typed in. A list of built-in pager functions can be found below. -`` is a valid normal or line-edit mode action. A detailed -description of these follows. - -### Normal mode actions +### Pager actions
**Name****Function** -
`NULL`Do nothing (used for disabling default keybindings) -
`QUIT`Exit the browser -
`CURSOR_UP`Move the cursor to the previous line -
`CURSOR_DOWN`Move cursor to the next line -
`CURSOR_LEFT`Move cursor to the previous cell -
`CURSOR_RIGHT`Move cursor to the next cell -
`CURSOR_LEFT`Move cursor to the previous cell -
`CURSOR_LINEBEGIN`Move cursor to the first cell of the line -
`CURSOR_LINEEND`Move cursor to the last cell of the line -
`CURSOR_NEXT_WORD`Move cursor to the beginning of the next word -
`CURSOR_PREV_WORD`Move cursor to the end of the previous word -
`CURSOR_NEXT_LINK`Move cursor to the beginning of the next clickable element -
`CURSOR_PREV_LINK`Move cursor to the beginning of the previous clickable element -
`PAGE_DOWN`Move screen down by one page -
`PAGE_UP`Move screen up by one page -
`PAGE_LEFT`Move screen to the left by one page -
`PAGE_RIGHT`Move screen to the right by one page -
`HALF_PAGE_DOWN`Move screen down by half a page -
`HALF_PAGE_UP`Move screen up by half a page -
`SCROLL_DOWN`Move screen down by one line -
`SCROLL_UP`Move screen up by one line -
`SCROLL_LEFT`Move screen to the left by one line -
`SCROLL_RIGHT`Move screen to the right by one line -
`CLICK`Click element currently under cursor -
`CHANGE_LOCATION`Go to URL -
`DUPE_BUFFER`Duplicate the current buffer -
`RELOAD`Reload page -
`RESHAPE`Reshape buffer (=render page anew) -
`REDRAW`Redraw buffer (=redraw screen) -
`TOGGLE_SOURCE`Source view -
`CURSOR_FIRST_LINE`Move cursor to the first line of the buffer -
`CURSOR_LAST_LINE`Move cursor to the last line of the buffer -
`CURSOR_TOP`Move cursor to the first line of the page -
`CURSOR_MIDDLE`Move cursor to the middle of the page -
`CURSOR_BOTTOM`Move cursor to the last line of the page -
`CENTER_LINE`Center screen around line -
`LINE_INFO`Display information about line -
`SEARCH`Search for a string in the current buffer -
`SEARCH_BACK`Search for a string, backwards -
`ISEARCH`Search for a string and highlight the first result -
`ISEARCH_BACK`Search and highlight the first result, backwards -
`SEARCH_NEXT`Jump to the next search result -
`SEARCH_PREV`Jump to the previous search result +
`pager.quit()`Exit the browser +
`pager.cursorUp()`Move the cursor to the previous line +
`pager.cursorDown()`Move cursor to the next line +
`pager.cursorLeft()`Move cursor to the previous cell +
`pager.cursorRight()`Move cursor to the next cell +
`pager.cursorLineBegin()`Move cursor to the first cell of the line +
`pager.cursorLineEnd()`Move cursor to the last cell of the line +
`pager.cursorNextWord()`Move cursor to the beginning of the next word +
`pager.cursorPrevWord()`Move cursor to the end of the previous word +
`pager.cursorNextLink()`Move cursor to the beginning of the next clickable element +
`pager.cursorPrevLink()`Move cursor to the beginning of the previous clickable element +
`pager.pageDown()`Move screen down by one page +
`pager.pageUp()`Move screen up by one page +
`pager.pageLeft()`Move screen to the left by one page +
`pager.pageRight()`Move screen to the right by one page +
`pager.halfPageDown()`Move screen down by half a page +
`pager.halfPageUp()`Move screen up by half a page +
`pager.scrollDown()`Move screen down by one line +
`pager.scrollUp()`Move screen up by one line +
`pager.scrollLeft()`Move screen to the left by one line +
`pager.scrollRight()`Move screen to the right by one line +
`pager.click()`Click element currently under cursor +
`pager.changeLocation()`Go to URL +
`pager.dupeBuffer()`Duplicate the current buffer +
`pager.reload()`Reload page +
`pager.reshape()`Reshape buffer (=render page anew) +
`pager.redraw()`Redraw buffer (=redraw screen) +
`pager.toggleSource()`Source view +
`pager.cursorFirstLine()`Move cursor to the first line of the buffer +
`pager.cursorLastLine()`Move cursor to the last line of the buffer +
`pager.cursorTop()`Move cursor to the first line of the page +
`pager.cursorMiddle()`Move cursor to the middle of the page +
`pager.cursorBottom()`Move cursor to the last line of the page +
`pager.centerLine()`Center screen around line +
`pager.lineInfo()`Display information about line +
`pager.searchForward()`Search for a string in the current buffer +
`pager.searchBackward()`Search for a string, backwards +
`pager.isearchForward()`Search for a string and highlight the first result +
`pager.isearchBackward()`Search and highlight the first result, backwards +
`pager.searchPrev()`Jump to the next search result +
`pager.searchNext()`Jump to the previous search result
### Line-editing actions
**Name****Function** -
`NULL`Do nothing -
`SUBMIT`Submit line -
`CANCEL`Cancel operation -
`BACKSPACE`Delete character before cursor -
`DELETE`Delete character after cursor -
`CLEAR`Clear text before cursor -
`KILL`Clear text after cursor -
`KILL_WORD`Delete previous word -
`BACK`Move cursor back by one character -
`FORWARD`Move cursor forward by one character -
`PREV_WORD`Move cursor to the previous word by one character -
`NEXT_WORD`Move cursor to the previous word by one character -
`BEGIN`Move cursor to the previous word by one character -
`END`Move cursor to the previous word by one character -
`ESC`Ignore keybindings for next character +
`line.submit()`Submit line +
`line.cancel()`Cancel operation +
`line.backspace()`Delete character before cursor +
`line.delete()`Delete character after cursor +
`line.clear()`Clear text before cursor +
`line.kill()`Clear text after cursor +
`line.clearWord(bounds)`Delete word before cursor[^a] +
`line.killWord(bounds)`Delete word after cursor[^a] +
`line.backward()`Move cursor back by one character +
`line.forward()`Move cursor forward by one character +
`line.prevWord(bounds)`Move cursor to the previous word by one character[^a] +
`line.nextWord(bounds)`Move cursor to the previous word by one character[^a] +
`line.begin()`Move cursor to the previous word by one character +
`line.end()`Move cursor to the previous word by one character +
`line.escape()`Ignore keybindings for next character
+ +Some entries have an optional `bounds` parameter. If passed, this must be a +JavaScript function with one parameter (the current unicode character), and +must return true if the passed character should count as a word boundary. + +```Examples: +# Control+A moves the cursor to the beginning of the line. +'C-a' = 'line.begin()' + +# Escape+D deletes everything after the cursor until it reaches a word-breaking +# character. +'M-d' = 'line.killWord()' + +# Control+W deletes everything before the cursor until it reaches a space. +'C-w' = 'line.clearWord(x => x == " ")' +``` -- cgit 1.4.1-2-gfad0