This commit merge the `CONTRIBUTING.md` and `doc/CONTRIBUTE.org` file
into a new `CONTRIBUTING.org` file. It also refactors the content to be
more organized and make its navigation more goal-oriented.
Github displays a link to the `CONTRIBUTING.*` file when people are
opening new issues or proposing new PRs. This file is important because
it is the entry-point to contributions guidelines for most of the users.
The current setup is non-optimal, even broken, as it adds a level of
indirection, and points to a contributing file that has broken
links (due to the new documentation format). The possible drawback of
the proposed solution is that I'm not sure if it is possible to include
it into the new online documentation as it is not in `doc/` folder.
The other possibility is to keep a small `CONTRIBUTING.md` file, as it
is now, pointing to the new documentation system (once online), but I'm
preferring the proposed solution for the following reasons:
- People that are willing to contribute will probably open Github
first (for forking, creating PR, etc), not the online documentation.
- It has one level of indirection less when people click on the
guidelines guide from a new issue/PR.
- `CONTRIBUTING.*` is by convention a special kind of file on github, so
it's valid reason to break the rule and not having it in the `doc/`
folder.
Prefix the "It is also recommended…" part of the Mac installation prerequisites with a note that this should be done *after* the basic install process.
This tripped me up and prevented initial installation. (The more detailed instructions and warnings added to Install since the current master will also help.)
Homebrew users expect a homebrew install to get them everything they need.
Because of this I've added a note indicating that you *also* need to do
the git clone mentioned at the top of the file.
XEmacs is packaged in many Linux distributions as "xemacs". Some may assume that "xemacs" and "emacs" have the same relationship as "gvim" and "vim", when in reality both packages have graphical support. Since I just had to correct this misunderstanding in someone, let's put it in the README to avoid it in the future.
I have seen many "I have a problem" discussions in the Gitter chat which
starts with a barrage of questions "Which OS? Which Emacs version?",
etc., so I thought it may be useful to have one function that will
generate the info to be copy-pasted into the Gitter chat and hence both
the user and others helping in the Gitter chat can jump directly to
solving the problem instead of the support volley to figure out the
setup.
Example output:
ELISP> (spacemacs/system-info)
"OS: darwin Emacs: 24.5.1 Spacemacs: 0.103.0 Spacemacs branch: develop
Layers: ((auto-completion :variables auto-completion-enable-help-tooltip
t) better-defaults emacs-lisp git markdown org (shell :variables
shell-default-height 30 shell-default-position (quote bottom))
syntax-checking version-control c-c++ clojure dash github html osx
python semantic sql)"
References:
From
https://github.com/syl20bnr/spacemacs/issues/2033#issuecomment-113861451 :
> Also what is your emacs version and OS ?
From
https://github.com/syl20bnr/spacemacs/issues/2042#issuecomment-113861501 :
> What's your Emacs version ? I presume it comes from the semantic
layer, can you test without the semantic layer ?
I noticed that the xkcd layer wasn't working on my windows box. After a little digging I found out that I was using the default download from the gnu emacs site which does not include the image support dlls. Hopefully this change will help people in the future in my same situation.
I cherry-picked it and played with it.
There is a major problem with this approach: all `after-init-hooks` will
be triggered right away because the hook is run before the end of the
alternate init
file ([source](https://groups.google.com/forum/#!topic/gnu.emacs.help/IrMz48PQykk))
. It leads to numerous errors, I fixed the spacemacs ones but obviously
I cannot fix the errors from packages. The remaining errors don't
prevent spacemacs from working but they give a very bad impression on
spacemacs quality with errors logs in `*Messages*`.
For those reasons I revert back this change as well as the documentation
I added.
https://github.com/syl20bnr/spacemacs/pull/520
The powerline color issue is due to the fact that Emacs 24.4 now
defaults to using sRGB colorspace on OS X 10.7 and higher, not some
"brokeness" with brew's `emacs` build as the previous verbiage seemed to
imply; the powerline codebase is still assuming `(setq
ns-use-srgb-colorspace nil)` is the default.
This PR adds more information about this so that users may
decide whether they want to just set it back to nil, switch to
emacs-mac (which has it set to nil anyway), or disable powershell
separators. (Turning off srgb colorspace results in washed-out theme
colors).
--------
Side rant:
I don't agree that the recommended fix for this would be to use
`emacs-mac-port` as that basically just gives better trackpad support.
IMHO trackpad support does not outweigh the frustrations over default
meta/super key bindings, no `server-start` support, or the use of the
antiquated carbon api, but I left the recommendation as-is in this PR.
Streamline descriptions and remove some lists of specific features. Also
reorder headings to focus on features with lists and pretty pictures to
make things more attractive.
I felt that drawing attention to specific Emacs packages in the readme
would be meaningless to people coming from Vim. They're covered in the
main documentation file anyway.
Properly define what a configuration layer is, and describe the main
roles of the ~/.spacemacs file.
Provide a brief overview on how to load config layers, since this is the
something users will probably want to do immediately.
Fix typos: Identified in review of c36a36fecf7
