TakeV
/
spacemacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Minor reformating of documentation files

This commit is contained in:
syl20bnr 2015-06-14 22:09:02 -04:00
parent 3ed0087cce
commit 920f01a776
4 changed files with 8 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
doc/CONTRIBUTE.org
View File

@ -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:*
1) Ideally and for /simple/ PRs:
*** 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/.

30
doc/CONVENTIONS.org
View File

@ -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.

178
doc/DOCUMENTATION.org
View File

File diff suppressed because it is too large Load Diff

6
doc/HOWTOs.org
View File

@ -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