From 6dc447cf5f0dd182dd40484c45bf72e4003591db Mon Sep 17 00:00:00 2001 From: person808 Date: Mon, 17 Apr 2017 20:05:28 -1000 Subject: [PATCH] Documentation fixes. Fixes: - Typo - Code block indentation - Put keybindings on one line so they look nicer when viewed in Spacemacs - Make one sentence sound better --- CONTRIBUTING.org | 4 +-- doc/BEGINNERS_TUTORIAL.org | 6 ++-- doc/DOCUMENTATION.org | 63 +++++++++++++++++++------------------- doc/FAQ.org | 18 +++++------ doc/VIMUSERS.org | 15 ++++----- 5 files changed, 54 insertions(+), 52 deletions(-) diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org index f25803792..72647eabe 100644 --- a/CONTRIBUTING.org +++ b/CONTRIBUTING.org @@ -116,7 +116,7 @@ Write commit messages according to adapted [[http://tbaggery.com/2008/04/19/a-no This is a model commit message: -#+begin_EXAMPLE +#+BEGIN_EXAMPLE Capitalized, short (72 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 @@ -138,7 +138,7 @@ Further paragraphs come after blank lines. single space, with blank lines in between, but conventions vary here - Use a hanging indent -#+end_EXAMPLE +#+END_EXAMPLE [[https://github.com/magit/magit/][Git Commit]] and [[https://github.com/magit/magit/][Magit]] provide Emacs mode for Git commit messages, which helps you to comply to these guidelines. diff --git a/doc/BEGINNERS_TUTORIAL.org b/doc/BEGINNERS_TUTORIAL.org index c99708308..fe5fa4d36 100644 --- a/doc/BEGINNERS_TUTORIAL.org +++ b/doc/BEGINNERS_TUTORIAL.org @@ -268,9 +268,9 @@ and effective plain-text system", but this gives only a small inkling of its versatility. If you do any kind of writing at all, chances are that Org mode will make it easier and more fun. This tutorial was written in Org mode. -Install the Org layer and open this tutorial. Make a copy named test.org with ~SPC f c~ -somewhere outside of the .emacs.d directory. Write ~SPC SPC org-mode RET~ to -switch to org mode from the write-only documentation mode. +Install the Org layer and open this tutorial. Make a copy named test.org with +~SPC f c~ somewhere outside of the .emacs.d directory. Write +~SPC SPC org-mode RET~ to switch to org mode from the write-only documentation mode. Press ~S-TAB~ repeatedly and observe that this cycles the visibility of the contents of different headlines. Press ~t~ in normal mode and observe that you diff --git a/doc/DOCUMENTATION.org b/doc/DOCUMENTATION.org index def71b57e..b14dd7870 100644 --- a/doc/DOCUMENTATION.org +++ b/doc/DOCUMENTATION.org @@ -567,12 +567,12 @@ configuration at the beginning and end of Spacemacs loading process: *** Custom variables By default custom variables from =M-x customize-group= are automatically saved at the end of your =~/.spacemacs= file in the function -=dotspacemacs/emacs-custom-settings== unless you declare a custom =custom-file= +=dotspacemacs/emacs-custom-settings= unless you declare a custom =custom-file= in the =dotspacemacs/user-init= function, in this case custom variables will be written to the user defined =custom-file= and the function =dotspacemacs/emacs-custom-settings= will remain empty. -*Note:* if you set a custom =custom-file= value then it is your responsibility +*Note:* If you set a custom =custom-file= value then it is your responsibility to load this file at the appropriate time. Often the best time to load it is just after setting the value for =custom-file= in the =dotspacemacs/user-init= function. @@ -587,12 +587,12 @@ layer=. For instance, [[Thank you][RMS]] can add his private configuration layer like this: #+BEGIN_SRC emacs-lisp -(setq-default dotspacemacs-configuration-layers - '( - ;; other layers - ;; rms layer added at the end of the list - rms - )) + (setq-default dotspacemacs-configuration-layers + '( + ;; other layers + ;; rms layer added at the end of the list + rms + )) #+END_SRC Official layers shipped with Spacemacs are stored in =~/.emacs.d/layers=. The @@ -788,10 +788,10 @@ Default configuration is: #+BEGIN_SRC emacs-lisp (setq-default dotspacemacs-editing-style '(hybrid :variables - hybrid-mode-enable-evilified-state t - hybrid-mode-enable-hjkl-bindings nil - hybrid-mode-use-evil-search-module nil - hybrid-mode-default-state 'normal) + hybrid-mode-enable-evilified-state t + hybrid-mode-enable-hjkl-bindings nil + hybrid-mode-use-evil-search-module nil + hybrid-mode-default-state 'normal) #+END_SRC To toggle the hybrid style on and off use ~SPC t E h~ and ~M-m t E h~. When @@ -1008,12 +1008,12 @@ fetch =zenburn= theme directly from the GitHub repository with the following declaration: #+BEGIN_SRC emacs-lisp -(setq-default dotspacemacs-themes - '(spacemacs-light - leuven - (zenburn :location (recipe :fetcher github - :repo "bbatsov/zenburn-emacs")) - )) + (setq-default dotspacemacs-themes + '(spacemacs-light + leuven + (zenburn :location (recipe :fetcher github + :repo "bbatsov/zenburn-emacs")) + )) #+END_SRC *Important note:* If you use =:location local= then you have to put your theme @@ -1650,8 +1650,8 @@ Additional text objects are defined in Spacemacs: these is *guaranteed* to never conflict with Spacemacs default key bindings. *Example:* Put =(spacemacs/set-leader-keys "oc" 'org-capture)= inside -=dotspacemacs/user-config= in your =~/.spacemacs= file, to be able to use ~SPC o -c~ to run org mode capture. +=dotspacemacs/user-config= in your =~/.spacemacs= file, to be able to use +~SPC o c~ to run org mode capture. ** Completion Spacemacs is powered by one of two incremental completion and selection @@ -2102,9 +2102,10 @@ the opened buffer and kill them. **** Special Buffers Unlike vim, emacs creates many buffers that most people do not need to see. Some -examples are =*Messages*= and =*Compile-Log*=. Spacemacs tries to automatically -ignore buffers that are not useful. However, you may want to change the way -Spacemacs marks buffers as useful. For instructions, see the [[file:FAQ.org::#change-special-buffer-rules][special buffer howto]]. +examples are the =*Messages*= and =*Compile-Log*= buffers. Spacemacs tries to +automatically ignore buffers that are not useful. However, you may want to +change the way Spacemacs marks buffers as useful. For instructions, see the +[[file:FAQ.org::#change-special-buffer-rules][special buffer howto]]. **** Files manipulations key bindings Files manipulation commands (start with ~f~): @@ -2247,8 +2248,8 @@ experience. **** Opening files with NeoTree By default a file is opened in the last active window. It is possible to choose -window number where to open a file by using a numeric argument, for instance ~2 -l~ or ~2 RET~ will open the current file in window 2. It is also possible to +window number where to open a file by using a numeric argument, for instance +~2 l~ or ~2 RET~ will open the current file in window 2. It is also possible to open the file in a split window with ~|~ and ~-~: | Key Binding | Description | @@ -2400,12 +2401,12 @@ Spacemacs can be interfaced with different search utilities like: - grep The search commands in Spacemacs are organized under the ~SPC s~ prefix with the -next key is the tool to use and the last key is the scope. For instance ~SPC s a -b~ will search in all opened buffers using =ag=. +next key is the tool to use and the last key is the scope. For instance +~SPC s a b~ will search in all opened buffers using =ag=. If the last key (determining the scope) is uppercase then the current region or -symbol under point is used as default input for the search. For instance ~SPC s -a B~ will search with symbol under point (if there is no active region). +symbol under point is used as default input for the search. For instance +~SPC s a B~ will search with symbol under point (if there is no active region). If the tool key is omitted then a default tool will be automatically selected for the search. This tool corresponds to the first tool found on the system of @@ -2891,8 +2892,8 @@ an ~occurrence~. - manual selection of several words then replace: ~v w w SPC s e S "toto" ESC ESC~ - append text to a word on two lines: ~v i w SPC s e J i "toto" ESC ESC~ - substitute symbol /with expand-region/: ~SPC v v e S "toto" ESC ESC~ -- replace symbol with yanked (copied) text /with expand region/: ~SPC v - e p ESC ESC~ +- replace symbol with yanked (copied) text /with expand region/: + ~SPC v e p ESC ESC~ *** Replacing text in several files If you have =rg=, =ag=, =pt= or =ack= installed, replacing an occurrence of text diff --git a/doc/FAQ.org b/doc/FAQ.org index dbaac721d..4a2379b39 100644 --- a/doc/FAQ.org +++ b/doc/FAQ.org @@ -156,10 +156,10 @@ conflict is to wrap your =org= config code in a =with-eval-after-load= block like this: #+BEGIN_SRC emacs-lisp -(with-eval-after-load 'org - ;; here goes your Org config :) - ;; .... - ) + (with-eval-after-load 'org + ;; Org config goes here + ;; .... + ) #+END_SRC ** Why is Spacemacs hanging on startup? @@ -418,11 +418,11 @@ For instance, if you want to switch ~SPC S~ (spelling) with ~SPC d~ (used by dash) to make the former easier to reach, you can use: #+BEGIN_SRC emacs-lisp -(defun dear-leader/swap-keys (key1 key2) - (let ((map1 (lookup-key spacemacs-default-map key1)) - (map2 (lookup-key spacemacs-default-map key2))) - (spacemacs/set-leader-keys key1 map2 key2 map1))) -(dear-leader/swap-keys "S" "d") + (defun dear-leader/swap-keys (key1 key2) + (let ((map1 (lookup-key spacemacs-default-map key1)) + (map2 (lookup-key spacemacs-default-map key2))) + (spacemacs/set-leader-keys key1 map2 key2 map1))) + (dear-leader/swap-keys "S" "d") #+END_SRC If you want to define your own alias, like using ~SPC é~ (because it's a not diff --git a/doc/VIMUSERS.org b/doc/VIMUSERS.org index 4ec3306e1..bbb64f41d 100644 --- a/doc/VIMUSERS.org +++ b/doc/VIMUSERS.org @@ -308,14 +308,15 @@ this: You can uncomment these suggested layers by deleting the semi-colons for a nice out-of-the-box experience. To add a layer, add its name to the list and restart -Emacs or press ~SPC f e R~ . To view all layers and their documentation use ~SPC -h SPC~. +Emacs or press ~SPC f e R~ . To view all layers and their documentation use +~SPC h SPC~. ** Creating a Layer To group configuration or when configuration doesn't fit well in your =.spacemacs= file, you can create a configuration layer. Spacemacs provides a -builtin command to generate the layer boilerplate: ~SPC SPC -configuration-layer/create-layer~. This generates a folder that looks like this: +builtin command to generate the layer boilerplate: +~SPC SPC configuration-layer/create-layer RET~. This generates a folder that +looks like this: #+BEGIN_EXAMPLE [layer-name] @@ -384,12 +385,12 @@ one can understand. Thanks to [[https://github.com/jwiegley/use-package][use-pac that allows easy lazy-loading and configuration of packages. Here are the basics to using it: -#+begin_src emacs-lisp +#+BEGIN_SRC emacs-lisp ;; Basic form of use-package declaration. The :defer t tells use-package to ;; try to lazy load the package. (use-package package-name :defer t) - ;; The :init section is run before the package loads The :config section is + ;; The :init section is run before the package loads. The :config section is ;; run after the package loads (use-package package-name :defer t @@ -404,7 +405,7 @@ to using it: (progn ;; Calling a function that is defined when the package loads (function-defined-when-package-loads))) -#+end_src +#+END_SRC This is just a very basic overview of =use-package=. There are many other ways to control how a package loads using it that aren't covered here.