diff --git a/content/docs/help.smd b/content/docs/help.smd new file mode 100644 index 0000000..06fdbaf --- /dev/null +++ b/content/docs/help.smd @@ -0,0 +1,224 @@ +--- +.title = "Flow Control: a programmer's text editor", +.date = @date("2020-07-06T00:00:00"), +.author = "CJ van den Berg", +.layout = "index.shtml", +.draft = false, +--- + +## Terminal configuration + +Most terminals have default keybindings that conflict with common editor +commands. I highly recommend rebinding them to keys that are not generally +used anywhere else. + +For Kitty rebinding `kitty_mod` by adding this line to your kitty.conf is +usually enough: +``` +kitty_mod ctrl+alt +``` + +For other editors you will probably have to disable or rebind them each +individually. + + +## Searching + +Press ctrl+f to search this help file. Type a search term and press +ctrl+n/ctrl+p or f3/shift+f3 to jump through the matches. Press Enter +to exit find mode at the current match or Escape to return to your +starting point. + + +## Messages and logs + +Messages of issues regarding tasks that are not accomplished, like +trying to close flow with unsaved files, as well as other information +are shown briefly in the bottom status bar; most recent messages can +be seen in the log view too, to open it, use ctrl+shift+p > `View log`; +it's possible to make it taller dragging the toolbar with the mouse +up or downwards. + + +## Input Modes + +Flow Control supports multiple input modes that may be changed +interactively at runtime. The current input mode (and some other +settings) is persisted in the configuration file automatically. + +- f4 => Cycle major input modes (flow, emacs, vim, helix,...) + +The current input mode is displayed at the left side of the statusbar. + +- ctrl+shift+p or alt+x => Show the command palette + +The command palette allows you to fuzzy search and select commands to run. It +also shows any available keybind that may be used to run the command without +opening the palette. + +- ctrl+f2 => Show all available commands and keybinds + +This shows all currently available commands. Including commands that are +normally only executed via a keybinding. Selecting a command in this view +will insert the command name into the current document instead of executing +it. This is very useful for editing keybinding definition files. + +Run the `Edit keybindings` command to save the current keybinding mode to a +file in the configuration `keys` directory and open it for editing. Save your +customized keybinds under a new name in the same directory to create an +entirely new keybinding mode that can be selected with `f4`. Delete the +keybinding file from the configuration `keys` directory to revert the mode +to it's built-in definition (if there is one). Changes to keybinding files +will take effect on restart. + +Keybinding modes may inherit all non-conflicting keybindings from another mode +by adding an `inherit` option to the `settings` section of the keybind file +like this: + +```json +{ + "settings": { + "inherit": "vim", + }, + "normal": { + ... +``` + +This allows you to make only minor additions/changes to an existing builtin +mode without copying the whole mode and is easier to keep up-to-date. + +Additionally, individual sub-modes may inherit all non-conflicting keybindings +from another sub-mode of the same mode by adding an `inherit` option to the +sub-mode section like this: + +``` + "normal": { + "inherit": "project", + ... +``` + +Multiple inheritance is supported with the `inherits` options like this: + +``` + "normal": { + "inherits": ["project", "tasks"], + ... +``` + +### Flow mode + +The default input mode, called just flow, is based on common GUI +programming editors. It most closely resembles Visual Studio Code, but +also takes some inspiration from Emacs and others. This mode focuses +on powerful multi cursor support with a find -> select -> modify +cycle style of editing. + +See the `ctrl+f2` palette when flow mode is selected to see the full +list of keybindings for this mode. + + +### Vim mode + +The vim modes, shown as NORMAL, INSERT or VISUAL in the status bar, +follow the basic modal editing style of vim. The basics follow vim +closely, but more advanced vim functions (e.g. macros and registers) +are not supported (yet). Keybindings from flow mode that do not conflict +with vim keybindings also work in vim mode. + + +### Helix mode + +The helix modes, shown as NOR, INS or SEL in the status bar, follow +the basic modal editing style of helix. The basics are being adapted +closely, more advanced functions (e.g. surround, macros, selections, +registers) are not supported (yet). Usual keybinding with LSPs are +used for tasks like 'go to definition', 'go to reference' and +'inline documentation' featuring inline diagnostics. Keybindings +from flow mode that do not conflict with helix keybindings also work in +helix mode. + +(work in progress) + +## Mouse Commands + +Mouse commands are NOT rebindable and are not listed in the command palette. + +- Left Click => + Clear all cursors and selections and the place cursor at the mouse pointer + +- Double Left Click => + Select word at mouse pointer + +- Triple Left Click => + Select line at mouse pointer + +- Drag Left Click => + Extend selection to mouse pointer + +- Alt + Left Click => + Add cursor at mouse click + +- Ctrl + Left Click => + Goto definition of symbol at click + +- hold Alt => + Enable jump/hover mouse mode + +- Right Click => + Extend selection to mouse pointer + +- Middle Click => + Close tab + +- Back Button, Forward Button => + Jump to previous/next location in the location history + +- Scroll Wheel => + Scroll + +- Alt + Scroll Wheel => + Fast scroll + +## Configuration + +Configuration is stored in the standard location +`${XDG_CONFIG_HOME}/flow/config.json`. This is usually +`~/.config/flow/config.json`. + +The default configuration will be written the first time +Flow Control is started and looks similar to this: +``` +frame_rate 60 +theme "default" +input_mode "flow" +gutter_line_numbers true +gutter_line_numbers_relative false +enable_terminal_cursor false +highlight_current_line true +highlight_current_line_gutter true +show_whitespace false +animation_min_lag 0 +animation_max_lag 150 +``` + +Most of these options are fairly self explanatory. + +`theme`, `input_mode` and `show_whitespace` are automatically +persisted when changed interactively with keybindings. + +`frame_rate` can be tuned to control the maximum number +of frames rendered. + +`animation_max_lag` controls the maximum amount of time allowed +for rendering scrolling animations. Set to 0 to disable scrolling +animation altogether. + +File types may be configured with the `Edit file type configuration` command. You +can also create a new file type by adding a new `.conf` file to the `file_type` +directory. Have a look at an existing file type to see what options are available. + +## Flags and options + +As every respectable terminal program, flow provide various invoking +options that among others, will allow you to inspect various aspects of +the running session. Feel free to run `flow --help` to explore them. diff --git a/content/docs/index.smd b/content/docs/index.smd index 2801891..b980cc6 100644 --- a/content/docs/index.smd +++ b/content/docs/index.smd @@ -1,11 +1,22 @@ --- -.title = "Flow Control - a programmer's text editor", +.title = "Documentation", .date = @date("2020-07-06T00:00:00"), .author = "CJ van den Berg", .layout = "index.shtml", .draft = false, --- +## Online help + +Flow Control has an online manual that is included in the `flow` binary. You can +open it directly in the editor by pressing `F1` or selecting the `Open help` +command. The manual is included here for convenience. + +* [Flow Control online help](/docs/help) + + +## Developer Resources + * [Architecture overview](/docs/architecture) * [Contributing](/docs/contributing) * [DeepWiki generated documentation](https://deepwiki.com/neurocyte/flow)