Extend documentation

This commit is contained in:
Daniel - 2019-12-17 12:25:04 +01:00
parent 0579025806
commit 6af610a203
No known key found for this signature in database
GPG Key ID: 1C7071A75BB72D64
1 changed files with 70 additions and 3 deletions

View File

@ -3,6 +3,69 @@
My personal Emacs Configuration, containing bits of code collected from around
the web. Have fun with it!
This configuration is known to work with Emacs 25.2 (and later) on
Debian GNU/Linux and Windows 10 (sigh).
* Features
- Tight integration of Org Mode, via customizable variables for different types
of Org Mode files, predefined capture templates, hydras, continuous clocking,
and more.
- Gnus integration, including a general setup to easily add SMTP configuration
for multiple email accounts.
- Extended completion support via [[https://github.com/emacs-helm/helm][helm]], [[https://github.com/abo-abo/swiper][ivy]], and [[https://company-mode.github.io/][company]].
- A custom “start menu” based on helm (via ~C-x g~), allowing to access
bookmarks, default applications, and files; see the documentation of
~db/helm-shortcuts~ for more details.
- More or less usable integration into Windows (necessary for work, sorry for
- Support for various programming languages (Emacs Lisp, Clojure, Python, LaTeX,
Perl, Haskell, …)
* Initial Setup
To use this configuration, either clone or download a copy of this repository
and place it in your =~/.emacs.d= directory (beware that under Windows, your
home directory may be anywhere, check the variable ~%HOME%~ for this).
If you use a proxy to access the Wild Internet™, make sure that the environment
variables ~http_proxy~ and ~https_proxy~ are set with the correct values. Upon
first start, Emacs will download all some packages it deems essential, so please
be patient. All subsequent starts should be much faster.
To make most of this configuration (and Emacs in general), a standard GNU
(POSIX?) user space is required. Under GNU/Linux system, this is standard, but
for Windows this may be a problem. The easiest way to get a minimal GNU user
space is to install [[https://git-scm.com/download/win][Git for Windows]] and augment your ~%PATH%~ to include
~C:\Program Files\Git\usr\bin\~ (or some-such). This way, executables like
~bash~, ~find~, ~grep~, and ~gpg~ are available to Emacs, but please be aware
that the naming convention for directories is different for these tools from the
Windows standard, i.e., ~/c/Windows/System32/~ instead of
~C:\Windows\System32\~. In general, this should not be a problem, though.
* Customization
This configuration allows to make some customization without touching the code
to adapt it to the need of the respective user. This is done using the
Customize interface of Emacs. Some of the variables are set to some default
values different from the default default values. However, those settings are
done before loading user customization, and thus can be overwritten by the
Additionally, some variables are provided that allow for additional
configuration. Those are located in the ~personal-settings~ Customization
group, which see, and come with some (and hopefully sufficient) documentation.
* Adding custom code
If customizing variables is not enough, you can of course always add you custom
code directly in the configuration. However, this may make future merges
difficult (in case you want to stay up-to-date with this configuration, that
is). To this end, a special variables called ~db/after-init-load-files~ can be
customized to contain a list of files that will be loaded as the last step
during startup of Emacs. This way, custom code stays outside of the main
configuration and future merges should pass without conflicts.
* Structure
The main configuration is available in the usual [[init.el]] file, with additional
@ -21,10 +84,14 @@ and global hooks. It also imports some environment variables and starts the
server when running under windows. Any additional packages are only loaded when
* Compatibility
Lastly, ~db/run-init~ loads all files contained in ~db/after-init-load-files~,
in that order.
This configuration is known to work with Emacs 25.2 (and later) on
Debian GNU/Linux and Windows 10 (sigh).
* Known Limitations
Under Windows, using Tramp using ~ssh~ from git does not seem to work because no
~ssh-askpass~ is included. Using passwordless authentication should work,
* License