Minor reformating of documentation files

doc/CONTRIBUTE.org

@@ -3,6 +3,9 @@
 ** Table of Contents                                                 :TOC@4:
  - [[#contribute-to-spacemacs][Contribute to Spacemacs]]
      - [[#pull-request-guidelines][Pull Request Guidelines]]
+         - [[#ideally-and-for-simple-prs][Ideally and for /simple/ PRs:]]
+         - [[#for-complex-pull-requests][For complex pull requests:]]
+         - [[#getting-help][Getting Help]]
      - [[#submitting-a-configuration-layer][Submitting a configuration layer]]
      - [[#submitting-a-banner][Submitting a banner]]
      - [[#credits][Credits]]
@@ -12,17 +15,13 @@
          - [[#contributor-of-a-contribution-layer][Contributor of a contribution layer]]
 
 ** Pull Request Guidelines
-
 =Spacemacs= branch model is inspired from the [[http://nvie.com/posts/a-successful-git-branching-model/][git-flow]] model:
 You'll have to submit your contributions and fixes within a pull-request to
 apply against the =develop= branch.
 
 /PR = pull request/
 
-*Guidelines:*
+*** Ideally and for /simple/ PRs:
-
-1) Ideally and for /simple/ PRs:
-
 -  branch from =develop=
 -  one topic per PR
 -  one commit per PR
@@ -35,20 +34,19 @@ apply against the =develop= branch.
 Those PRs are /fast-forwarded/ whenever it's possible and
 /cherry-picked/ otherwise (most likely they will be cherry-picked).
 
-2) For complex pull requests:
+*** For complex pull requests:
-
 -  squash only the commits with uninteresting changes like typos, syntax
    fixes, etc... and keep the important and /isolated/ steps in
    different commits.
 
 Those PRs are /merged/ and explicitly /not fast-forwarded/.
 
-*Getting Help:* If you have any question on this process, join the [[https://gitter.im/syl20bnr/spacemacs][gitter
+*** Getting Help
+If you have any question on this process, join the [[https://gitter.im/syl20bnr/spacemacs][gitter
 chatroom]] and ask your questions there. It will be a pleasure to help you to
 contribute!
 
 ** Submitting a configuration layer
-
 Contributed configuration layers are stored in the =contrib= folder. The
 =contrib= folder also contains categories prefixed with =!= to put your
 layers in. For example a layer for a language would go in the
@@ -64,7 +62,6 @@ add it at the top of the =README.md= before the TOC. The maximum
 recommended height is 200 pixels.
 
 ** Submitting a banner
-
 The startup banner is by default randomly chosen among a pool of banners
 each time =Spacemacs= starts. Banners are located in directory
 =~/.emacs.d/core/banners=.
@@ -75,9 +72,7 @@ You are free to choose a reasonable height size but the width size
 should be around 75 characters.
 
 ** Credits
-
 *** License
-
 The license is GPLv3 for all parts specific to =Spacemacs=, this
 includes: - the initialization and core files - all the layer files.
 
@@ -86,7 +81,6 @@ refer to the header file. Those files should not have an empty header,
 please report any file imported in =Spacemacs= without a proper header.
 
 *** File header
-
 Template:
 
 #+BEGIN_EXAMPLE
@@ -104,7 +98,6 @@ Template:
 #+END_EXAMPLE
 
 *** Author of a contribution layer
-
 In the file header: - change =NAME= to the name of the layer, - change
 the default author name =Sylvain Benner= to your name, - do not remove
 the line: =;; Copyright (c) 2012-2014 Sylvain Benner= - modify the
@@ -112,7 +105,6 @@ second copyright line by replacing the default name and dates, *keep*
 =& Contributors= in this line, - other lines should not be modified
 
 *** Contributor of a contribution layer
-
 You should not modify any header file. A very cool way to show your
 contributions will be available in Spacemacs at some point, /Stay
 Tuned/.

doc/CONVENTIONS.org

@@ -35,9 +35,7 @@
          - [[#help-or-documentation][Help or Documentation]]
 
 ** Code guidelines
-
 *** Spacemacs core and layer
-
 Function names follow these conventions:
   - =spacemacs/xxx= is an interactive function called =xxx=
   - =spacemacs//xxx= is a private function called =xxx= (implementation details)
@@ -48,7 +46,6 @@ Variables follow these conventions:
   - =spacemacs--xxx= is a private variable (implementation details)
 
 *** All layers
-
 A package is initialized in a function with name =<layer>/init-xxx= where:
   - =<layer>= is the layer name
   - =xxx= is the package name
@@ -56,18 +53,14 @@ A package is initialized in a function with name =<layer>/init-xxx= where:
 ** Key bindings conventions
 
 *** Reserved prefix
-
 **** User prefix
-
 ~SPC o~ must not be used by any layer. It is reserved for the user.
 
 **** 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 ~,~.
 
 **** Micro-state
-
 Whenever possible a micro-state should be enabled with ~M-SPC~ and ~s-M-SPC~. We
 need the latter bindings on OS X since ~M-SPC~ is used by the OS for spotlight.
 
@@ -77,7 +70,6 @@ buffers are good candidates to be put on ~M-SPC~ and ~s-M-SPC~.
 It is recommended to add ~q~ to leave the micro-state.
 
 *** Evilify buffers
-
 =Spacemacs= offers convenient functions to /evilify/ a buffer.
 /Evilifying/ a buffer is to set the =evilified state= as the default
 state for the major mode of the buffer.
@@ -98,9 +90,7 @@ and so on...
 Example of /evilified/ buffers are =magit status=, =paradox buffer=.
 
 *** Navigation
-
 **** n and N
-
 To be consistent with the Vim way, ~n~ and ~N~ are favored over Emacs ~n~ and
 ~p~.
 
@@ -110,7 +100,6 @@ each time the prefix commands. More info on micro-states in the
 [[DOCUMENTATION.org#micro-states][documentation]].
 
 **** Code Navigation
-
 The prefix for going to something is ~SPC m g~.
 
 | Key     | Description                                |
@@ -121,7 +110,6 @@ The prefix for going to something is ~SPC m g~.
 | ~m g t~ | go to corresponding test file if any       |
 
 **** =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.
 
@@ -131,7 +119,6 @@ should be performed with ~C-j~ and ~C-k~ bindings for vertical movements.
 | ~C-k~ | go up       |
 
 *** Evaluation
-
 Live evaluation of code is under the prefix ~SPC m e~.
 
 | Key     | Description                                       |
@@ -144,9 +131,7 @@ Live evaluation of code is under the prefix ~SPC m e~.
 | ~m e r~ | evaluate region                                   |
 
 *** REPLs
-
 **** Send code
-
 A lot of languages can interact with a REPL. To help keeping a
 consistent behavior between those languages the following conventions
 should be followed:
@@ -172,7 +157,6 @@ should be followed:
 Note: we don't distinguish between the file and the buffer.
 
 **** In terminal
-
 History navigation in shells or REPLs buffers should be bound as well to
 ~C-j~ and ~C-k~.
 
@@ -184,7 +168,6 @@ History navigation in shells or REPLs buffers should be bound as well to
     | ~C-r~ | search backward in history |
 
 *** Building and Compilation
-
 The base prefix for major mode specific compilation is ~SPC m c~.
 
     | Key Binding | Description       |
@@ -197,7 +180,6 @@ 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
-
 The base prefix for debugging commands is ~SPC d~.
 
 | Key Binding | Description             |
@@ -220,12 +202,10 @@ Notes:
     upstream (major mode repository).
 
 *** Plain Text Markup Languages
-
 For layers supporting markup languages please follow the following
 keybindings whenever applicable.
 
 **** Headers
-
 All header functionality should be grouped under ~SPC m h~
 
 | Key Binding | Description                                      |
@@ -235,7 +215,6 @@ All header functionality should be grouped under ~SPC m h~
 | ~m h 1..10~ | Insert a header of level 1..10 (if possible)     |
 
 **** Insertion of common elements
-
 Insertion of common elements like links or footnotes should be grouped
 under ~SPC m i~
 
@@ -248,7 +227,6 @@ under ~SPC m i~
 | ~m i w~     | Insert wiki-link |
 
 **** Text manipulation
-
 Manipulation of text regions should be grouped under ~SPC m r~
 
 | Key Binding | Description                   |
@@ -263,7 +241,6 @@ Manipulation of text regions should be grouped under ~SPC m r~
 | ~m x v~     | Make region verbose           |
 
 **** Movement in normal mode
-
 In normal mode Vim style movement should be enabled with these keybindings:
 
 | Key Binding | Description                            |
@@ -274,7 +251,6 @@ In normal mode Vim style movement should be enabled with these keybindings:
 | ~g l~       | Move down one level in headings        |
 
 **** Promotion, Demotion and element movement
-
 Promotion, demotion and movement of headings or list elements (whatever is
 possible) should be enabled with the following keys in any mode
 
@@ -286,19 +262,16 @@ possible) should be enabled with the following keys in any mode
 | ~M-l~       | Demote heading by one level  |
 
 **** Table editing
-
 If table specific commands are available the they are grouped under the
 ~SPC m t~ group.
 
 *** Tests
-
 A lot of languages have their own test frameworks. These frameworks
 share common actions that we can unite under the same key bindings: -
 ~SPC m t~ is the prefix for test execution. - ~SPC m T~ is the
 prefix for test execution in debug mode (if supported).
 
 **** All languages
-
 | Key     | Description                                         |
 |---------+-----------------------------------------------------|
 | ~m t a~ | execute all the tests of the current project        |
@@ -310,7 +283,6 @@ implement an auto-save of the buffer before executing the tests of
 buffer.
 
 **** Language specific
-
 | Key     | Description                             |
 |---------+-----------------------------------------|
 | ~m t m~ | execute the tests of the current module |
@@ -320,11 +292,9 @@ Note that there are overlaps, depending on the language we will choose
 one or more bindings for the same thing
 
 *** Refactoring
-
 Refactoring prefix is ~SPC m r~.
 
 *** Help or Documentation
-
 The base prefix for help commands is ~SPC h~. Documentation is considered
 as an help command.
 

doc/HOWTOs.org

@@ -9,7 +9,6 @@
      - [[#enable-navigation-by-visual-lines][Enable navigation by visual lines]]
 
 ** Disable a package completely
-
 To completely disable a package and effectively uninstalling it even if
 it is part of your used layers, look for the variable
 =dotspacemacs-excluded-packages= in your dotfile and add the package
@@ -20,7 +19,6 @@ name to it:
 #+end_src
 
 ** Disable a package only for a specific major-mode
-
 This is done by removing the hook added by Spacemacs. For example to
 remove =flycheck= support in python buffers, look for the function
 =dotspacemacs/config= in your dotfile and add the following code:
@@ -33,7 +31,6 @@ remove =flycheck= support in python buffers, look for the function
 ~SPC h d v major-mode RET~
 
 ** Disable company for a specific major-mode
-
 It may be handy to disable =company= for a given mode if you plan on
 configuring =auto-complete= instead. On easy way to do it is to use the
 macro =spacemacs|disable-company= in the function =dotspacemacs/config=
@@ -45,7 +42,6 @@ of your dotfile. The following snippet disables company for
 #+end_src
 
 ** Change special buffer rules
-
 To change the way spacemacs marks buffers as useless, you can customize
 =spacemacs-useless-buffers-regexp= which marks buffers matching the
 regexp as useless. The variable =spacemacs-useful-buffers-regexp= marks
@@ -53,7 +49,6 @@ buffers matching the regexp as useful buffers. Both can be customized
 the same way.
 
 Examples:
-
 #+begin_src emacs-lisp
     ;; Only mark helm buffers as useless
     (setq spacemacs-useless-buffers-regexp '("\\*helm\.\+\\*"))
@@ -63,7 +58,6 @@ Examples:
 #+end_src
 
 ** Enable navigation by visual lines
-
 Add the following snippet to your =dostpacemacs/config= function:
 
 #+begin_src emacs-lisp