diff --git a/doc/CONVENTIONS.md b/doc/CONVENTIONS.md index 4bfa4f8b6..4ba88ec8d 100644 --- a/doc/CONVENTIONS.md +++ b/doc/CONVENTIONS.md @@ -8,9 +8,12 @@ - [Spacemacs core and layer](#spacemacs-core-and-layer) - [All layers](#all-layers) - [Key bindings conventions](#key-bindings-conventions) - - [Prefix reserved to the user](#prefix-reserved-to-the-user) - - [Prefix reserved to the current major mode](#prefix-reserved-to-the-current-major-mode) - - [Navigation between items](#navigation-between-items) + - [Reserved prefix](#reserved-prefix) + - [User prefix](#user-prefix) + - [Major mode prefix](#major-mode-prefix) + - [Navigation](#navigation) + - [Navigation with n and N](#navigation-with-n-and-n) + - [Code Navigation](#code-navigation) - [In buffer evaluation of code](#in-buffer-evaluation-of-code) - [Interactions with REPLs](#interactions-with-repls) - [Interactions with Tests](#interactions-with-tests) @@ -18,10 +21,9 @@ - [Depending on the language](#depending-on-the-language) - [Building and Compilation](#building-and-compilation) - [Debugging](#debugging) - - [Code navigation](#code-navigation) - [Getting Help or Documentation](#getting-help-or-documentation) - - [Evilify buffers](#evilify-buffers) - [Navigation in `insert state` buffers](#navigation-in-insert-state-buffers) + - [Evilify buffers](#evilify-buffers) @@ -46,17 +48,21 @@ A package is initialized in a function with name `/init-xxx` where: ## Key bindings conventions -### Prefix reserved to the user +### Reserved prefix + +#### User prefix SPC o must not be used by any layer. It is reserved for the user. -### Prefix reserved to the current major mode +#### Major mode prefix SPC m is reserved for the current major mode. Three keys bindings are not an issue (ie. SPC m h d) since SPC m can be accessed via ,. -### Navigation between items +### Navigation + +#### Navigation with n and N To be consistent with the Vim way, n and N are favored over Emacs n and p. @@ -66,18 +72,28 @@ A micro-state allows to repeat key bindings without entering each time the prefix commands. More info on micro-states in the [documentation](DOCUMENTATION.md#micro-states). -### In buffer evaluation of code +#### Code Navigation -Live evaluation of code is under the prefix ` e`. +The prefix for going to something is ` m g`. Key | Description ------------------|------------------------------------------------------------ -e $ | put the point at the end of the line and evaluate -e b | evaluate buffer -e e | evaluate last expression -e f | evaluate function -e l | evaluate line -e r | evaluate region +m g a | go to alternate file (i.e. `.h <--> .cpp`) +m g g | go to things under point +m g t | go to corresponding test file if any + +### In buffer evaluation of code + +Live evaluation of code is under the prefix ` m e`. + + Key | Description +------------------|------------------------------------------------------------ +m e $ | put the point at the end of the line and evaluate +m e b | evaluate buffer +m e e | evaluate last expression +m e f | evaluate function +m e l | evaluate line +m e r | evaluate region ### Interactions with REPLs @@ -122,7 +138,7 @@ common actions that we can unite under the same key bindings: m t t | execute the current test (thing at point, function) Note: we don't distinguish between the file and the buffer. We can implement -an auto-save of the buffer before executing the tests. +an auto-save of the buffer before executing the tests of buffer. #### Depending on the language @@ -140,8 +156,12 @@ The base prefix for major mode specific compilation is SPC m c. Key Binding | Description ---------------------|------------------------------------------------------------ +m c b | compile buffer m c c | compile -m c r | recompile +m c r | clean and compile + +Note: we don't distinguish between the file and the buffer. We can implement +an auto-save of the buffer before compiling the buffer. ### Debugging @@ -152,9 +172,9 @@ The base prefix for debugging commands is SPC d. m d a | abandon current process m d b | toggle a breakpoint m d c | continue current process -m d d | start debug process m d n | next breakpoint m d N | previous breakpoint +m d s | start debug process Notes: - Ideally a micro-state for breakpoint navigation should be provided. @@ -162,12 +182,6 @@ Notes: the spacemacs level and ideally the function should be proposed as a patch upstream (major mode repository). -### Code navigation - - Key | Description -------------------|------------------------------------------------------------ -m g | go to definition of thing under point - ### Getting Help or Documentation The base prefix for help commands is SPC h. Documentation is @@ -175,7 +189,27 @@ considered as an help command. Key | Description ------------------|------------------------------------------------------------ -m h d | documentation of thing under point +m h h | documentation of thing under point +m h r | documentation of selected region + +### Navigation in `insert state` buffers + +Navigation in buffers like `Helm` and `ido` which are in `insert state` should +be performed with C-j and C-k bindings for vertical +movements. + + Key | Description +----------------|------------------------------------------------------------ +C-j | go down +C-k | go up + +History navigation in shells or REPLs buffers should be bound as well to +C-j and C-k. + + Key | Description +----------------|------------------------------------------------------------ +C-j | next item in history +C-k | previous item in history ### Evilify buffers @@ -196,22 +230,3 @@ Example of _evilified_ buffers are `magit status`, `paradox buffer`. The related functions are: - `spacemacs/activate-evil-leader-for-maps` and `spacemacs/activate-evil-leader-for-map` - `spacemacs/evilify` - -### Navigation in `insert state` buffers - -Navigation in buffers like `Helm` and `ido` which are in `insert state` should -be performed with C-j and C-k bindings for vertical -movements. - - Key | Description -----------------|------------------------------------------------------------ -C-j | go down -C-k | go up - -History navigation in shells or REPLs buffers should be bound as well to -C-j and C-k. - - Key | Description -----------------|------------------------------------------------------------ -C-j | next item in history -C-k | previous item in history