Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 123 lines (95 sloc) 5.666 kB
5fcb34d @technomancy initial commit
technomancy authored
1 # Emacs Starter Kit
2
b191b8b @technomancy Readme updates. Link manual downloads to version 23.
technomancy authored
3 The Starter Kit should provide a saner set of defaults than you get
4 normally with Emacs. It was originally intended for beginners, but it
5 should provide a reasonable working environment for anyone using Emacs
6 for dynamic languages. It also bundles a number of useful libraries
7 that are not distributed with Emacs for various reasons.
0a9f568 @technomancy Mostly readme updates; a few other small tweaks.
technomancy authored
8
dc4f2e4 @technomancy Documentation updates.
technomancy authored
9 The latest version is at http://github.com/technomancy/emacs-starter-kit/
10
0a9f568 @technomancy Mostly readme updates; a few other small tweaks.
technomancy authored
11 ## Learning
12
13 This won't teach you Emacs, but it'll make it easier to get
14 comfortable. To access the tutorial, press control-h followed by t.
15
16 You may also find the [PeepCode Meet Emacs
dc4f2e4 @technomancy Documentation updates.
technomancy authored
17 screencast](http://peepcode.com/products/meet-emacs) helpful. The
18 [Emacs Wiki](http://emacswiki.org) is also very handy.
5fcb34d @technomancy initial commit
technomancy authored
19
20 ## Installation
21
5d72d8e @technomancy Update installation notes and mention Aquamacs is unsupported in the …
technomancy authored
22 1. Install GNU Emacs (at least version 22, 23 is preferred)
bc4d490 @technomancy trying to fix readme; not sure how markdown works.
technomancy authored
23 Use your package manager if you have one.
b191b8b @technomancy Readme updates. Link manual downloads to version 23.
technomancy authored
24 Otherwise Mac users may get [some prebuilt binaries](http://emacsformacosx.com/), and
25 Windows users can get them [from GNU](http://ftp.gnu.org/pub/gnu/emacs/windows/emacs-23.1-bin-i386.zip).
5d72d8e @technomancy Update installation notes and mention Aquamacs is unsupported in the …
technomancy authored
26 2. Move the directory containing this file to ~/.emacs.d
27 (If you already have a directory at ~/.emacs.d move it out of the
28 way and put this there instead.)
5fcb34d @technomancy initial commit
technomancy authored
29 3. Launch Emacs!
30
5d72d8e @technomancy Update installation notes and mention Aquamacs is unsupported in the …
technomancy authored
31 If you find yourself missing some autoloads after an update (which
32 should manifest itself as "void function: foobar" errors) try M-x
33 regen-autoloads. After some updates an M-x recompile-init will be
34 necessary; this should be noted in the commit messages.
47667cb @technomancy Added some autoloads; updated README.
technomancy authored
35
36 If you want to keep your regular ~/.emacs.d in place and just launch a
37 single instance using the starter kit, try the following invocation:
38
39 $ emacs -q -l ~/src/emacs-starter-kit/init.el
40
188f12b @technomancy Clarified a few installation notes in the README.
technomancy authored
41 Note that having a ~/.emacs file might override the starter kit
42 loading, so if you've having trouble loading it, make sure that file
43 is not present.
44
c0912d8 @technomancy Updated README with a note about structure.
technomancy authored
45 ## Structure
46
47 The init.el file is where everything begins. It's the first file to
48 get loaded. The starter-kit-* files provide what I consider to be
49 better defaults, both for different programming languages and for
50 built-in Emacs features like bindings or registers.
51
52 Files that are pending submission to ELPA are bundled with the starter
53 kit under the directory elpa-to-submit/. The understanding is that
54 these are bundled just because nobody's gotten around to turning them
55 into packages, and the bundling of them is temporary. For these
56 libraries, autoloads will be generated and kept in the loaddefs.el
57 file. This allows them to be loaded on demand rather than at startup.
58
59 There are also a few files that are meant for code that doesn't belong
60 in the Starter Kit. First, the user-specific-config file is the file
61 named after your user with the extension ".el". In addition, if a
62 directory named after your user exists, it will be added to the
63 load-path, and any elisp files in it will be loaded. Finally, the
64 Starter Kit will look for a file named after the current hostname
65 ending in ".el" which will allow host-specific configuration. This is
66 where you should put code that you don't think would be useful to
67 everyone. That will allow you to merge with newer versions of the
68 starter-kit without conflicts.
69
b95c632 @technomancy Doc updates, textile-mode, and a haml fix.
technomancy authored
70 ## Emacs Lisp Package Archive
5fcb34d @technomancy initial commit
technomancy authored
71
dc4f2e4 @technomancy Documentation updates.
technomancy authored
72 Libraries from [ELPA](http://tromey.com/elpa) are preferred when
5fcb34d @technomancy initial commit
technomancy authored
73 available since dependencies are handled automatically, and the burden
0a9f568 @technomancy Mostly readme updates; a few other small tweaks.
technomancy authored
74 to update them is removed from the user. In the long term, ideally
75 everything would be installed via ELPA, and only package.el would need
76 to be distributed with the starter kit. (Or better yet, package.el
77 would come with Emacs...) See starter-kit-elpa.el for a list of
c0912d8 @technomancy Updated README with a note about structure.
technomancy authored
78 libraries that are pending submission to ELPA. Packages get installed
79 in the elpa/ directory.
6d0a2f7 @technomancy Extract regen-autoloads function.
technomancy authored
80
dc4f2e4 @technomancy Documentation updates.
technomancy authored
81 There's no vendor/ directory in the starter kit because if an external
82 library is useful enough to be bundled with the starter kit, it should
83 be useful enough to submit to ELPA so that everyone can use it, not
84 just users of the starter kit.
85
ad5705f @technomancy Instructions for how to work around ELPA upgrade problems.
technomancy authored
86 Sometimes packages are removed from the Starter Kit as they get added
87 to ELPA itself. This has occasionally caused problems with certain
88 packages. If you run into problems with such a package, try removing
89 everything from inside the elpa/ directory and invoking M-x
90 starter-kit-elpa-install in a fresh instance.
91
5d72d8e @technomancy Update installation notes and mention Aquamacs is unsupported in the …
technomancy authored
92 ## Variants of Emacs
93
94 The Starter Kit is designed to work with GNU Emacs version 22 or
95 greater. Using it with forks or other variants is not supported. It
96 probably won't work with XEmacs, though some have reported getting it
97 to work with Aquamacs. However, since Aquamacs is not portable,
b191b8b @technomancy Readme updates. Link manual downloads to version 23.
technomancy authored
98 it's difficult to test in it, and breakage is common.
5d72d8e @technomancy Update installation notes and mention Aquamacs is unsupported in the …
technomancy authored
99
5fcb34d @technomancy initial commit
technomancy authored
100 ## Contributing
101
102 If you know your way around Emacs, please try out the starter kit as a
103 replacement for your regular dotfiles for a while. If there's anything
8b83d57 @technomancy Tweak a few variables, change the package list.
technomancy authored
104 you just can't live without, add it or let me know so I can add
105 it. Take a look at what happens in init.el to get started.
5fcb34d @technomancy initial commit
technomancy authored
106
0a9f568 @technomancy Mostly readme updates; a few other small tweaks.
technomancy authored
107 Also: see the file TODO. Helping submit new libraries to ELPA is the
488f7f7 @technomancy Some docs about submitting to elpa.
technomancy authored
108 easiest way to help out. There are two ways you can do this: either
109 take new libraries and make them ready for ELPA, dropping them in the
110 elpa-to-submit directory or take files that are already in
111 elpa-to-submit, ensuring all their dependencies are correctly loaded
112 into ELPA, and sending them to the ELPA maintainer. There are details
113 at http://tromey.com/elpa/upload.html for how ELPA submission
114 works. Grep the project for TODO for other things.
c0912d8 @technomancy Updated README with a note about structure.
technomancy authored
115
b95c632 @technomancy Doc updates, textile-mode, and a haml fix.
technomancy authored
116 Files are licensed under the same license as Emacs unless otherwise
117 specified. See the file COPYING for details.
118
c0912d8 @technomancy Updated README with a note about structure.
technomancy authored
119 The latest version is at http://github.com/technomancy/emacs-starter-kit/
acc7e69 @technomancy Installation note in the readme for poor souls on w32.
technomancy authored
120
121 On Unix, /home/$USER/.emacs.d, on windows Documents and Settings/%your
122 user name%/Application Data
Something went wrong with that request. Please try again.