Flatten the structure a bit

init.org

@@ -5,13 +5,13 @@
 
 * About
 
-  This is an Emacs configuration file written in [[http://orgmode.org][Org mode]]. It is an attempt
+  This is an Emacs configuration file written in [[http://orgmode.org][Org mode]]. It is an attempt to
-  to keep my =~/.emacs.d= tidy, but still be able to keep it all in one
+  keep my =~/.emacs.d= tidy, but still be able to keep it all in one file. I
-  file. I aim to briefly explain all my configurations as I go along!
+  aim to briefly explain all my configurations as I go along!
 
-  I would not recommend using this configuration /as-is/, because it
+  I would not recommend using this configuration /as-is/, because it probably
-  probably contains a lot you don't really need. I do, however, hope people
+  contains a lot you don't really need. I do, however, hope people find some
-  find some golden nuggets that they can smuggle into their own configs.
+  golden nuggets that they can smuggle into their own configs.
 
   If you really do want to try this config out, this is how I'd go about it:
 
@@ -47,28 +47,28 @@
 
   #+end_src
 
-  On first run it should install a bunch of packages (this might take a
+  On first run it should install a bunch of packages (this might take a while),
-  while), and you might have to restart your Emacs the first time. If you
+  and you might have to restart your Emacs the first time. If you experience
-  experience bugs, please let me know!
+  bugs, please let me know!
 
 * Configurations
-** Meta
+* Meta
 
   All changes to the configuration should be done in =init.org=, *not* in
  =init.el=. Any changes in the =init.el= will be overwritten by saving
- =init.org=. The =init.el= in this repo should not be tracked by git, and
+ =init.org=. The =init.el= in this repo should not be tracked by git, and is
-   is replaced the first time Emacs is started (assuming it has been renamed
+  replaced the first time Emacs is started (assuming it has been renamed to
-   to =~/.emacs.d=).
+ =~/.emacs.d=).
 
-   Emacs can't load =.org=-files directly, but =org-mode= provides functions
+  Emacs can't load =.org=-files directly, but =org-mode= provides functions to
-   to extract the code blocks and write them to a file. There are multiple
+  extract the code blocks and write them to a file. There are multiple ways of
-   ways of handling this; like suggested by [[http://emacs.stackexchange.com/questions/3143/can-i-use-org-mode-to-structure-my-emacs-or-other-el-configuration-file][this StackOverflow post]], one
+  handling this; like suggested by [[http://emacs.stackexchange.com/questions/3143/can-i-use-org-mode-to-structure-my-emacs-or-other-el-configuration-file][this StackOverflow post]], one could just use
-   could just use =org-babel-load-file=, but I had problems with
+ =org-babel-load-file=, but I had problems with byte-compilation. Previously I
-   byte-compilation. Previously I tracked both the =org.=- and =el.=-files,
+  tracked both the =org.=- and =el.=-files, but the git commits got a little
-   but the git commits got a little messy. So here is a new approach.
+  messy. So here is a new approach.
 
-   When this configuration is loaded for the first time, the ~init.el~ is
+  When this configuration is loaded for the first time, the ~init.el~ is the
-   the file that is loaded. It looks like this:
+  file that is loaded. It looks like this:
 
   #+begin_src emacs-lisp :tangle no
 
@@ -90,8 +90,8 @@
   It tangles the org-file, so that this file is overwritten with the actual
   configuration.
 
-   There is no reason to track the =init.el= that is generated; by running
+  There is no reason to track the =init.el= that is generated; by running the
-   the following command =git= will not bother tracking it:
+  following command =git= will not bother tracking it:
 
   #+begin_src sh :tangle no
 
@@ -99,8 +99,8 @@
 
   #+end_src
 
-   If one wishes to make changes to the repo-version of =init.el= start
+  If one wishes to make changes to the repo-version of =init.el= start tracking
-   tracking again with:
+  again with:
 
   #+begin_src sh :tangle no
 
@@ -117,13 +117,13 @@
 
   #+end_src
 
-   The =init.el= should (after the first run) mirror the source blocks in
+  The =init.el= should (after the first run) mirror the source blocks in the
-   the =init.org=. We can use =C-c C-v t= to run =org-babel-tangle=, which
+ =init.org=. We can use =C-c C-v t= to run =org-babel-tangle=, which extracts
-   extracts the code blocks from the current file into a source-specific
+  the code blocks from the current file into a source-specific file (in this
-   file (in this case a =.el=-file).
+  case a =.el=-file).
 
-   To avoid doing this each time a change is made we can add a function to
+  To avoid doing this each time a change is made we can add a function to the
-   the =after-save-hook= ensuring to always tangle and byte-compile the
+ =after-save-hook= ensuring to always tangle and byte-compile the
  =org=-document after changes.
 
   #+begin_src emacs-lisp
@@ -172,13 +172,13 @@
 
   #+end_src
 
-** Packages
+* Packages
 
-   Managing extensions for Emacs is simplified using =package= which is
+  Managing extensions for Emacs is simplified using =package= which is built in
-   built in to Emacs 24 and newer. To load downloaded packages we need to
+  to Emacs 24 and newer. To load downloaded packages we need to initialize
-   initialize =package=. =cl= is a library that contains many functions from
+ =package=. =cl= is a library that contains many functions from Common Lisp,
-   Common Lisp, and comes in handy quite often, so we want to make sure it's
+  and comes in handy quite often, so we want to make sure it's loaded, along
-   loaded, along with =package=, which is obviously needed.
+  with =package=, which is obviously needed.
 
   #+begin_src emacs-lisp
 
@@ -186,8 +186,8 @@
 
   #+end_src
 
-   Packages can be fetched from different mirrors, [[http://melpa.milkbox.net/#/][melpa]] is the largest
+  Packages can be fetched from different mirrors, [[http://melpa.milkbox.net/#/][melpa]] is the largest archive
-   archive and is well maintained.
+  and is well maintained.
 
   #+begin_src emacs-lisp
 
@@ -202,8 +202,8 @@
 
   #+end_src
 
-   The configuration assumes that the packages listed below are
+  The configuration assumes that the packages listed below are installed. To
-   installed. To ensure we install missing packages if they are missing.
+  ensure we install missing packages if they are missing.
 
   #+begin_src emacs-lisp
 
@@ -272,14 +272,14 @@
 
   #+end_src
 
-** Mac OS X
+* Mac OS X
 
-   I run this configuration mostly on Mac OS X, so we need a couple of
+  I run this configuration mostly on Mac OS X, so we need a couple of settings
-   settings to make things work smoothly. In the package section
+  to make things work smoothly. In the package section =exec-path-from-shell=
- =exec-path-from-shell= is included (only if you're running OS X), this is
+  is included (only if you're running OS X), this is to include
-   to include environment-variables from the shell. It makes using Emacs
+  environment-variables from the shell. It makes using Emacs along with
-   along with external processes a lot simpler. I also prefer using the
+  external processes a lot simpler. I also prefer using the =Command=-key as
- =Command=-key as the =Meta=-key.
+  the =Meta=-key.
 
   #+begin_src emacs-lisp
 
@@ -296,7 +296,7 @@
 
   #+end_src
 
-** Sane defaults
+* Sane defaults
 
   These are what /I/ consider to be saner defaults.
 
@@ -355,8 +355,8 @@
 
   #+end_src
 
-   Answering /yes/ and /no/ to each question from Emacs can be tedious, a
+  Answering /yes/ and /no/ to each question from Emacs can be tedious, a single
-   single /y/ or /n/ will suffice.
+ /y/ or /n/ will suffice.
 
   #+begin_src emacs-lisp
 
@@ -409,7 +409,7 @@
 
   #+end_src
 
-** Modes
+* Modes
 
   There are some modes that are enabled by default that I don't find
   particularly useful. We create a list of these modes, and disable all of
@@ -447,11 +447,11 @@
 
   #+end_src
 
-** Visual
+* Visual
 
   I am using a lot from [[https://github.com/rougier/nano-emacs][rougier's N Λ N O Emacs]], starting with the theme.
 
-*** Theme
+** Theme
 
    For the light theme, I keep the light background toned down a touch.
 
@@ -500,7 +500,7 @@
 
    #+end_src
 
-*** Mode line
+** Mode line
 
    This is the default setup for [[https://github.com/rougier/nano-modeline][N Λ N O Modeline]] after version 1.0.0:
 
@@ -545,7 +545,7 @@
    (add-to-list 'default-frame-alist '(internal-border-width . 24))
    #+end_src
 
-*** Font
+** Font
 
    Pick the first of the following fonts that is installed on the system.
 
@@ -574,7 +574,7 @@
 
    #+end_src
 
-*** Centering with Olivetti
+** Centering with Olivetti
 
    [[https://github.com/rnkn/olivetti][Olivetti]] is a package that simply centers the text of a buffer. It is very
    simple and beautiful. The default width is just a bit short.
@@ -587,7 +587,7 @@
 
    #+end_src
 
-** Dashboard
+* Dashboard
 
   #+begin_src emacs-lisp
   (require 'dashboard)
@@ -601,12 +601,12 @@
                           (bookmarks . 5)))
   #+end_src
 
-** Ivy
+* Ivy
 
   [[http://oremacs.com/swiper/][Ivy]] is a completion system, giving you completions and fuzzy search whenever
-   you interact with the minibuffer. I transitioned to Ivy from [[https://emacs-helm.github.io/helm/][Helm]], mainly
+  you interact with the minibuffer. I transitioned to Ivy from [[https://emacs-helm.github.io/helm/][Helm]], mainly due
-   due to it being aesthetically noisy, and that I didn't fully take advantage
+  to it being aesthetically noisy, and that I didn't fully take advantage of
-   of all its features (which are numerous). Here are some customization's that
+  all its features (which are numerous). Here are some customization's that
   made the transition a bit easier.
 
   #+begin_src emacs-lisp
@@ -624,7 +624,7 @@
 
   #+end_src
 
-** PDF Tools
+* PDF Tools
 
   [[https://github.com/politza/pdf-tools][PDF Tools]] makes a huge improvement on the built-in [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][doc-view-mode]]; the only
   drawback is the =pdf-tools-install= (which has to be executed before the
@@ -645,13 +645,13 @@
 
   #+end_src
 
-** Completion
+* Completion
 
-   [[https://github.com/auto-complete/auto-complete][Auto-Complete]] has been a part of my config for years, but I want to try
+  [[https://github.com/auto-complete/auto-complete][Auto-Complete]] has been a part of my config for years, but I want to try out
-   out [[http://company-mode.github.io/][company-mode]]. If I code in an environment with good completion, I've
+  [[http://company-mode.github.io/][company-mode]]. If I code in an environment with good completion, I've made an
-   made an habit of trying to /guess/ function-names, and looking at the
+  habit of trying to /guess/ function-names, and looking at the completions for
-   completions for the right one. So I want a pretty aggressive completion
+  the right one. So I want a pretty aggressive completion system, hence the no
-   system, hence the no delay settings and short prefix length.
+  delay settings and short prefix length.
 
   #+begin_src emacs-lisp
 
@@ -665,7 +665,7 @@
 
   #+end_src
 
-** Spelling
+* Spelling
 
   Flyspell offers on-the-fly spell checking. We can enable flyspell for all
   text-modes with this snippet.
@@ -692,11 +692,11 @@
   (setq ispell-program-name "aspell")
   #+end_src
 
-   When working with several languages, we should be able to cycle through
+  When working with several languages, we should be able to cycle through the
-   the languages we most frequently use. Every buffer should have a separate
+  languages we most frequently use. Every buffer should have a separate cycle
-   cycle of languages, so that cycling in one buffer does not change the
+  of languages, so that cycling in one buffer does not change the state in a
-   state in a different buffer (this problem occurs if you only have one
+  different buffer (this problem occurs if you only have one global cycle). We
-   global cycle). We can implement this by using a [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Closures.html][closure]].
+  can implement this by using a [[http://www.gnu.org/software/emacs/manual/html_node/elisp/Closures.html][closure]].
 
   #+begin_src emacs-lisp
 
@@ -714,11 +714,11 @@
 
   #+end_src
 
- =flyspell= signals an error if there is no spell-checking tool is
+ =flyspell= signals an error if there is no spell-checking tool is installed.
-   installed. We can advice =turn-on-flyspell= and =flyspell-prog-mode= to
+  We can advice =turn-on-flyspell= and =flyspell-prog-mode= to only try to
-   only try to enable =flyspell= if a spell-checking tool is available. Also
+  enable =flyspell= if a spell-checking tool is available. Also we want to
-   we want to enable cycling the languages by typing =C-c l=, so we bind the
+  enable cycling the languages by typing =C-c l=, so we bind the function
-   function returned from =cycle-languages=.
+  returned from =cycle-languages=.
 
   #+begin_src emacs-lisp
 
@@ -738,10 +738,10 @@
 
   #+end_src
 
-** Org
+* Org
 
-   When editing org-files with source-blocks, we want the source blocks to
+  When editing org-files with source-blocks, we want the source blocks to be
-   be themed as they would in their native mode.
+  themed as they would in their native mode.
 
   #+begin_src emacs-lisp
 
@@ -772,21 +772,21 @@
 
   #+end_src
 
-** Direnv
+* Direnv
 
   I use [[https://direnv.net][direnv]] in combination with [[https://nixos.org][nix]] to allow for programs to only be
-   available in certain directories. The [[https://github.com/wbolster/emacs-direnv][emacs-direnv]] makes Emacs play nice
+  available in certain directories. The [[https://github.com/wbolster/emacs-direnv][emacs-direnv]] makes Emacs play nice with
-   with direnv, so that it for instance can detect a language server that is
+  direnv, so that it for instance can detect a language server that is only
-   only available within some project. The =direnv-always-show-summary= is set
+  available within some project. The =direnv-always-show-summary= is set to
-   to =nil= to avoid having long messages pop up in the messages buffer
+ =nil= to avoid having long messages pop up in the messages buffer whenever I
-   whenever I enter a directory that interacts with direnv.
+  enter a directory that interacts with direnv.
 
   #+begin_src emacs-lisp
   (direnv-mode 1)
   (setq direnv-always-show-summary nil)
   #+end_src
 
-** Email
+* Email
 
   I've used Emacs for email in the past, where I've always had the need for a
   more standard email client in addition. I'm going to give it another go.
@@ -852,7 +852,7 @@
 
   #+end_src
 
-** ChatGPT
+* ChatGPT
 
   I have a line like this:
 
@@ -871,15 +871,14 @@
 
   #+end_src
 
-** Interactive functions
+* Interactive functions
   <<sec:defuns>>
 
- =just-one-space= removes all whitespace around a point - giving it a
+ =just-one-space= removes all whitespace around a point - giving it a negative
-   negative argument it removes newlines as well. We wrap a interactive
+  argument it removes newlines as well. We wrap a interactive function around
-   function around it to be able to bind it to a key. In Emacs 24.4
+  it to be able to bind it to a key. In Emacs 24.4 =cycle-spacing= was
- =cycle-spacing= was introduced, and it works like =just-one-space=, but
+  introduced, and it works like =just-one-space=, but when run in succession it
-   when run in succession it cycles between one, zero and the original
+  cycles between one, zero and the original number of spaces.
-   number of spaces.
 
   #+begin_src emacs-lisp
 
@@ -892,12 +891,11 @@
 
   #+end_src
 
-   Often I want to find other occurrences of a word I'm at, or more
+  Often I want to find other occurrences of a word I'm at, or more specifically
-   specifically the symbol (or tag) I'm at. The
+  the symbol (or tag) I'm at. The =isearch-forward-symbol-at-point= in Emacs
- =isearch-forward-symbol-at-point= in Emacs 24.4 works well for this, but
+  24.4 works well for this, but I don't want to be bothered with the =isearch=
-   I don't want to be bothered with the =isearch= interface. Rather jump
+  interface. Rather jump quickly between occurrences of a symbol, or if non is
-   quickly between occurrences of a symbol, or if non is found, don't do
+  found, don't do anything.
-   anything.
 
   #+begin_src emacs-lisp
 
@@ -928,12 +926,12 @@
 
   #+end_src
 
-   I sometimes regret killing the =*scratch*=-buffer, and have realized I
+  I sometimes regret killing the =*scratch*=-buffer, and have realized I never
-   never want to actually kill it. I just want to get it out of the way, and
+  want to actually kill it. I just want to get it out of the way, and clean it
-   clean it up. The function below does just this for the
+  up. The function below does just this for the =*scratch*=-buffer, and works
- =*scratch*=-buffer, and works like =kill-this-buffer= for any other
+  like =kill-this-buffer= for any other buffer. It removes all buffer content
-   buffer. It removes all buffer content and buries the buffer (this means
+  and buries the buffer (this means making it the least likely candidate for
-   making it the least likely candidate for =other-buffer=).
+ =other-buffer=).
 
   #+begin_src emacs-lisp
 
@@ -986,9 +984,9 @@
 
   #+end_src
 
-   Org mode does currently not support synctex (which enables you to jump from
+  Org mode does currently not support synctex (which enables you to jump from a
-   a point in your TeX-file to the corresponding point in the pdf), and it
+  point in your TeX-file to the corresponding point in the pdf), and it [[http://comments.gmane.org/gmane.emacs.orgmode/69454][seems
-   [[http://comments.gmane.org/gmane.emacs.orgmode/69454][seems like a tricky problem]].
+  like a tricky problem]].
 
   Calling this function from an org-buffer jumps to the corresponding section
   in the exported pdf (given that the pdf-file exists), using pdf-tools.
@@ -1017,11 +1015,11 @@
       (fill-paragraph nil (region-active-p))))
   #+end_src
 
-** Advice
+* Advice
 
   An advice can be given to a function to make it behave differently. This
-   advice makes =eval-last-sexp= (bound to =C-x C-e=) replace the sexp with
+  advice makes =eval-last-sexp= (bound to =C-x C-e=) replace the sexp with the
-   the value.
+  value.
 
   #+begin_src emacs-lisp
 
@@ -1037,10 +1035,9 @@
 
   #+end_src
 
-   When interactively changing the theme (using =M-x load-theme=), the
+  When interactively changing the theme (using =M-x load-theme=), the current
-   current custom theme is not disabled. This often gives weird-looking
+  custom theme is not disabled. This often gives weird-looking results; we can
-   results; we can advice =load-theme= to always disable themes currently
+  advice =load-theme= to always disable themes currently enabled themes.
-   enabled themes.
 
   #+begin_src emacs-lisp
 
@@ -1050,7 +1047,7 @@
 
   #+end_src
 
-** global-scale-mode
+* global-scale-mode
 
   These functions provide something close to ~text-scale-mode~, but for every
   buffer, including the minibuffer and mode line.
@@ -1198,11 +1195,11 @@
 
 *** Common lisp
 
-    I use [[http://www.common-lisp.net/project/slime/][Slime]] along with =lisp-mode= to edit Common Lisp code. Slime
+    I use [[http://www.common-lisp.net/project/slime/][Slime]] along with =lisp-mode= to edit Common Lisp code. Slime provides
-    provides code evaluation and other great features, a must have for a
+    code evaluation and other great features, a must have for a Common Lisp
-    Common Lisp developer. [[http://www.quicklisp.org/beta/][Quicklisp]] is a library manager for Common Lisp,
+    developer. [[http://www.quicklisp.org/beta/][Quicklisp]] is a library manager for Common Lisp, and you can
-    and you can install Slime following the instructions from the site along
+    install Slime following the instructions from the site along with this
-    with this snippet.
+    snippet.
 
     #+begin_src emacs-lisp
 
@@ -1247,9 +1244,9 @@
 
 ** C
 
-   The =c-mode-common-hook= is a general hook that work on all C-like
+   The =c-mode-common-hook= is a general hook that work on all C-like languages
-   languages (C, C++, Java, etc...). I like being able to quickly compile
+   (C, C++, Java, etc...). I like being able to quickly compile using =C-c C-c=
-   using =C-c C-c= (instead of =M-x compile=), a habit from =latex-mode=.
+   (instead of =M-x compile=), a habit from =latex-mode=.
 
    #+begin_src emacs-lisp
 
@@ -1262,8 +1259,8 @@
 
 ** Java
 
-   Some statements in Java appear often, and become tedious to write
+   Some statements in Java appear often, and become tedious to write out. We
-   out. We can use abbrevs to speed this up.
+   can use abbrevs to speed this up.
 
    #+begin_src emacs-lisp
 
@@ -1301,8 +1298,7 @@
 
 ** LaTeX and org-mode LaTeX export
 
- =.tex=-files should be associated with =latex-mode= instead of
+ =.tex=-files should be associated with =latex-mode= instead of =tex-mode=.
- =tex-mode=.
 
    #+begin_src emacs-lisp
 
@@ -1335,8 +1331,8 @@
 
    #+end_src
 
-   I like using the [[https://code.google.com/p/minted/][Minted]] package for source blocks in LaTeX. To make org
+   I like using the [[https://code.google.com/p/minted/][Minted]] package for source blocks in LaTeX. To make org use
-   use this we add the following snippet.
+   this we add the following snippet.
 
    #+begin_src emacs-lisp
 
@@ -1349,8 +1345,8 @@
    Because [[https://code.google.com/p/minted/][Minted]] uses [[http://pygments.org][Pygments]] (an external process), we must add the
  =-shell-escape= option to the =org-latex-pdf-process= commands. The
  =tex-compile-commands= variable controls the default compile command for
-   Tex- and LaTeX-mode, we can add the flag with a rather dirty statement
+   Tex- and LaTeX-mode, we can add the flag with a rather dirty statement (if
-   (if anyone finds a nicer way to do this, please let me know).
+   anyone finds a nicer way to do this, please let me know).
 
    #+begin_src emacs-lisp
 
@@ -1423,8 +1419,8 @@
 
 ** Haskell
 
- =haskell-doc-mode= is similar to =eldoc=, it displays documentation in
+ =haskell-doc-mode= is similar to =eldoc=, it displays documentation in the
-   the echo area. Haskell has several indentation modes - I prefer using
+   echo area. Haskell has several indentation modes - I prefer using
  =haskell-indent=.
 
    #+begin_src emacs-lisp
@@ -1544,12 +1540,11 @@
 
 * Key bindings
 
-  Inspired by [[http://stackoverflow.com/questions/683425/globally-override-key-binding-in-emacs][this StackOverflow post]] I keep a =custom-bindings-map= that
+  Inspired by [[http://stackoverflow.com/questions/683425/globally-override-key-binding-in-emacs][this StackOverflow post]] I keep a =custom-bindings-map= that holds
-  holds all my custom bindings. This map can be activated by toggling a
+  all my custom bindings. This map can be activated by toggling a simple
-  simple =minor-mode= that does nothing more than activating the map. This
+ =minor-mode= that does nothing more than activating the map. This inhibits
-  inhibits other =major-modes= to override these bindings. I keep this at
+  other =major-modes= to override these bindings. I keep this at the end of the
-  the end of the init-file to make sure that all functions are actually
+  init-file to make sure that all functions are actually defined.
-  defined.
 
   #+begin_src emacs-lisp