emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update READMEs & add new ones

Browse source
This commit is contained in:
Henrik Lissner 2017-05-25 20:08:50 +02:00
parent 9d1af37dee
commit e1f60b2bfd
13 changed files with 529 additions and 92 deletions
Download patch file Download diff file Expand all files Collapse all files

64
README.md
View file

@ -26,23 +26,45 @@ git clone https://github.com/hlissner/.emacs.d ~/.emacs.d
cd ~/.emacs.d
cp init.example.el init.el # maybe edit init.el
make install
make compile # optional, may take a while
make compile-lite # optional (lighter alternative to compile)
# If you have problems, run this to diagnose any common problems
# DOOM is designed to benefit from byte compilation, it can boost startup time
# and make Emacs feel a bit snappier, but it is OPTIONAL.
make compile # may take a while
# or
make compile-lite # lighter alternative to compile
# If you have problems, run this to check for common issues with your setup
make doctor
```
If you change `init.el` or add/remove functions to autoload files, run `make`.
That is the equivalent of running:
If you byte-compile, changes to the config will **not** take effect until you
recompile or delete the byte-compiled files (with `make clean`).
## Package Management
Plugins can be managed from the command line with `make`:
```bash
make install # or (doom/packages-install)
make autoloads # or (doom/reload-autoloads)
make install # install missing plugins
make update # update installed plugins
make autoremove # remove unused plugins
# be sure to run install and autoremove after modifying init.el
# run this if you change autoload files
make autoloads
# you can run any make command with DEBUG=1 for extra logging, and YES=1 to
# auto-accept confirmation prompts:
DEBUG=1 make install
YES=1 make update
```
You can run any Make command with `DEBUG=1` for added logging verbosity, and
`YES=1` to auto-accept any confirmation prompts.
These can also be invoked from within emacs:
+ `doom/packages-install`
+ `doom/packages-update`
+ `doom/packages-autoremove`
+ `doom/reload-autoloads`
## Deciphering my emacs.d
@ -83,8 +105,8 @@ So you want to grok some of this madness. Here are a few suggestions:
(see `:ag` and `:rg`)
* Project search & replace with **[wgrep]**
* Interactive buffer search with **[swiper]**
* REPLs & inline/live code evaluation (using **[quickrun]**) with languages
support for Ruby, Python, PHP, JS, Elisp, Haskell, Lua and more.
* Inline/live code evaluation (using **[quickrun]**) and REPLs for a variety of
languages, including Ruby, Python, PHP, JS, Elisp, Haskell, Lua and more.
* [Minimalistic diffs in the fringe][sc-diffs] with **[git-gutter-fringe]**.
* A do-what-I-mean jump-to-definition implementation that tries its darnest to
find the definition of what you're looking at. It tries major-mode commands,
@ -102,13 +124,24 @@ So you want to grok some of this madness. Here are a few suggestions:
* RSS feed reader (using elfeed)
* Word Processor (using LaTeX, Org and Markdown)
## Contributing or troubleshooting
## Troubleshooting
My config wasn't intended for public use, but I'm happy to help you use or crib
from my config. I welcome contributions of any kind; documentation, bug
fixes/reports, even elisp tips.
from my config.
[Don't hesitate to tell me my Elisp-fu sucks](https://github.com/hlissner/.emacs.d/issues/new)!
+ If you have questions, drop me line at henrik@lissner.net.
+ If you have issues running or setting up my Emacs config, use `make doctor` to
help diagnose the issue before you report an issue.
+ If you still can't make sense of it, run `DEBUG=1 make doctor` and include
it [with your bug report][new-issue].
**And please include steps to reproduce your issue, if possible**.
## Contributing
I welcome contributions of any kind; documentation, bug fixes/reports, extra
modules, even elisp tips. Really,
[don't hesitate to tell me my Elisp-fu sucks][new-issue]!
[ag]: https://github.com/ggreer/the_silver_searcher
@ -124,6 +157,7 @@ fixes/reports, even elisp tips.
[git-gutter-fringe]: https://melpa.org/#/git-gutter-fringe
[ivy]: https://melpa.org/#/ivy
[neotree]: https://melpa.org/#/neotree
[new-issue]: https://github.com/hlissner/.emacs.d/issues/new
[persp-mode]: https://melpa.org/#/persp-mode
[quickrun]: https://melpa.org/#/quickrun
[rg]: https://github.com/BurntSushi/ripgrep

22
TODO.org
View file

@ -5,7 +5,7 @@
+ [-] Work-in-progress
+ [X] Complete
** Planned [6/76]
** Planned [11/76]
+ [0/14] Potential plugins
+ [ ] completion/ivy: [[https://github.com/yevgnen/ivy-rich][ivy-rich]], possible replacement for my ivy-buffer modifications (undecided)
+ [ ] app/present: [[https://github.com/larstvei/Focus][focus]], for presenting code
@ -26,7 +26,7 @@
+ [ ] app/irc
+ [-] app/crm
+ [-] app/write
+ [6/58] Add README.org's (with working babel blocks?) to modules (see [[modules/lang/go/README.org][lang/go/README.org]]) to replace bootstaps
+ [11/58] Add README.org's (with working babel blocks?) to modules (see [[modules/lang/go/README.org][lang/go/README.org]]) to replace bootstaps
+ [0/9] :tools
+ [ ] dired
+ [ ] electric-indent
@ -37,7 +37,7 @@
+ [ ] term
+ [ ] tmux
+ [ ] upload
+ [3/25] :lang
+ [5/25] :lang
+ [ ] assembly
+ [X] cc
+ [ ] crystal
@ -45,7 +45,7 @@
+ [ ] data
+ [ ] emacs-lisp
+ [X] go
+ [ ] haskell
+ [X] haskell
+ [ ] java
+ [ ] javascript
+ [ ] julia
@ -53,7 +53,7 @@
+ [ ] lua
+ [ ] markdown
+ [ ] org
+ [ ] php
+ [X] php
+ [ ] python
+ [X] rest
+ [ ] ruby
@ -63,9 +63,9 @@
+ [ ] swift
+ [ ] typescript
+ [ ] web
+ [0/10] :feature
+ [1/10] :feature
+ [ ] debug
+ [ ] eval
+ [X] eval
+ [ ] evil
+ [ ] file-templates
+ [ ] jump
@ -74,15 +74,15 @@
+ [ ] syntax-checker
+ [ ] version-control
+ [ ] workspaces
+ [1/5] :ui
+ [2/5] :ui
+ [X] doom
+ [ ] doom-dashboard
+ [ ] doom-modeline
+ [X] doom-modeline
+ [ ] doom-quit
+ [ ] hl-todo
+ [1/4] :completion
+ [2/4] :completion
+ [X] ivy
+ [ ] company
+ [X] company
+ [ ] ido
+ [ ] helm
+ [1/5] :app

31
modules/app/email/README.org
View file

@ -1,18 +1,21 @@
* Email
* :app email
I want to live in Emacs, but as we all know, living is incomplete without email.
So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing
combined with org-mode for writing emails? Yes please.
It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email
via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand).
This module makes Emacs an email client, using ~mu4e~.
#+begin_quote
My config is gmail/gsuite oriented, and since Google has its own opinions on the
IMAP standard, it is unlikely to translate to other hosts.
I want to live in Emacs, but as we all know, living is incomplete without email. So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing combined with org-mode for writing emails? /Yes please./
It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand).
WARNING: my config is gmail/gsuite oriented, and since Google has its own opinions on the IMAP standard, it is unlikely to translate to other hosts.
#+end_quote
** Installation
** Install
This module requires:
+ ~offlineimap~ (to sync mail with)
+ ~mu~ (to index your downloaded messages)
*** MacOS
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew install mu --with-emacs
@ -24,11 +27,10 @@ brew install offlineimap
sudo pacman --noconfirm --needed -S offlineimap mu
#+END_SRC
** Setup
First, you need to set up, download and index your email:
** Dependencies
You need to do the following:
1. Write a ~\~/.offlineimaprc~. Mine can be found [[https://github.com/hlissner/dotfiles/tree/master/shell/%252Bmu][in my dotfiles repository]]. It
is configured to download mail to ~\~/.mail~.
1. Write a ~\~/.offlineimaprc~. Mine can be found [[https://github.com/hlissner/dotfiles/tree/master/shell/%252Bmu][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I use unix pass to securely store my login credentials.
2. Download your email: ~offlineimap -o~ (may take a while)
3. Index it with mu: ~mu index --maildir ~/.mail~
@ -48,3 +50,4 @@ Then configure Emacs to use your email address:
(mu4e-compose-signature . "---\nHenrik Lissner"))
t)
#+END_SRC

39
modules/completion/company/README.org Normal file
View file

@ -0,0 +1,39 @@
* :completion company
This module adds completion support powered by [[https://github.com/company-mode/company-mode][company]].
+ Uses ~company-quickhelp~ for documentation tooltips
+ Uses ~company-statistics~ to order results by usage frequency
[[/../screenshots/company.png]]
** Install
Specific languages may require additional setup. Some languages may have no completion support at all.
Check the README.org in that language's module for details.
** Customization
This module is configured to suit my preferences. Here are some things you may want to change:
*** as-you-type completion
By default, I've disabled auto-completion. This is my preference. I prefer to invoke company when I need it by pressing ~C-SPC~ from insert mode. Some don't like this.
To make it automatic, you need to do two things:
1. Load ~company~,
2. and change ~company-idle-delay~ to a non-nil float (the default is 0.5)
To do this, add the following to your ~modules/private/<username>~ module (remember, ~:private <username>~ needs to be added to init.el):
#+BEGIN_SRC emacs-lisp
(require 'company)
(setq company-idle-delay 0.2
company-minimum-prefix-length 3)
#+END_SRC
** Troubleshooting
If completion isn't working for you, please consider the following before posting a bug report:
+ Different languages will have different dependencies in order for auto-completion to work. Please look for the README.org in that language's respective module for details.
+ Some languages don't have any auto-completion support.
+ Check [[*Customization][Customization]], perhaps what you are expecting is popup-as-you-type completion, which is disabled by default.

21
modules/completion/ivy/README.org
View file

@ -1,28 +1,31 @@
* Ivy
* :completion ivy
Ivy is my completion backend of choice (over ido and helm), for its speed and
simplicity. With ivy's help and some hackery, I get the following features:
This module adds the Ivy completion backend.
+ Project-wide search & replace.
I prefer ivy over ido and helm, for its speed and simplicity. With ivy's help and some hackery, I get the following features:
+ Project-wide search & replace powered by ~rg~ (falls back to ~ag~)
+ Project jump-to navigation ala Command-T, Sublime Text's Jump-to-anywhere or Vim's CtrlP plugin.
+ Ivy integration for ~M-x~, ~imenu~, ~recentf~ and others.
+ A powerful, interactive in-buffer search using ~swiper~.
+ Ivy-powered TODO/FIXME navigation
** Dependencies
This module depends only on [[https://github.com/BurntSushi/ripgrep][ripgrep]].
** Install
This module optionally depends on [[https://github.com/BurntSushi/ripgrep][ripgrep]] and [[https://github.com/ggreer/the_silver_searcher][the_silver_searcher]].
~rg~ is faster, but its results aren't deterministic and it doesn't support multiline search or full PCRE, that's where ~ag~ is useful.
*** MacOS
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew install ripgrep
brew install ripgrep the_silver_searcher
#+END_SRC
*** Arch Linux
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --needed --noconfirm -S ripgrep
sudo pacman --needed --noconfirm -S ripgrep the_silver_searcher
#+END_SRC
** Highlights
** Usage
*** Search & Replace
A project-wide search can be performed with Ag (the silver searcher) or Rg
(ripgrep) via their ex commands: ~:ag[!]~ and ~:rg[!]~ (or their

109
modules/feature/eval/README.org Normal file
View file

@ -0,0 +1,109 @@
* :feature eval
This module adds support for:
+ [[#repls][Defining, invoking & interacting with REPLs]],
+ [[#build-tasks][Defining & invoking build tasks for projects and files]],
+ and [[#code-evaluation][evaluating code or entire buffers, printing their output to a popup window]].
** Install
This module has no external dependencies. However, specific languages may require additional setup.
Check the README.org in that language's module for details.
** Usage
+ *REPLs*
Invoked via:
+ ~:repl~ (evil ex-command)
+ =<leader> o r= in normal mode (or visual mode, which sends the selection to the open REPL)
+ ~M-x +eval/repl~
+ ~M-x +eval/repl-send-region~ while a selection (and REPL) is active
+ *Build Tasks*
You will be prompted to select a task. Only the ones that meet the predicate will be listed.
+ ~:build~ (evil ex-command)
+ =M-b= (by default)
+ =<leader> o b= in normal mode
+ ~M-x +eval/build~
+ *Code Evaluation*
Quickrun can be invoked via:
+ ~M-x +eval/buffer~ (or ~gR~, or ~M-r~)
+ ~M-x +eval/region~
+ ~M-x +eval/region-and-replace~
+ Evil users can use the ~gr~ operator to select and run a region.
** Configuration
*** REPLs
REPLs have been defined for most of the languages DOOM supports (check its README.org to see if it does).
Otherwise, you can define your own:
A REPL definition consists of two parts: an interactive command that opens (and returns) a REPL buffer and a ~:repl~ definition that maps a major-mode to said command:
#+BEGIN_SRC emacs-lisp
(defun +emacs-lisp/repl ()
(interactive)
(pop-to-buffer
(or (get-buffer "*ielm*")
(progn (ielm)
(let ((buf (get-buffer "*ielm*")))
(bury-buffer buf)
buf)))))
(set! :repl 'emacs-lisp-mode #'+emacs-lisp/repl)
#+END_SRC
*** Build Tasks
A build task is little more than major-mode-local commands, comprised of an interactive command, an association with a major mode and an optional predicate function.
#+BEGIN_SRC emacs-lisp
(defun +lua/run-love ()
"Run the current project in love 10.0."
(async-shell-command
(format "/usr/bin/love %s"
(shell-quote-argument (doom-project-root)))))
(defun +lua/build ()
"Run a build script in the project root."
(let ((default-directory (doom-project-root)))
(compile "luajit build.lua")))
(defun +lua/generate-docs ()
"Generate project documentation."
(let ((default-directory (doom-project-root)))
(compile "luadoc *.lua")))
(defun +lua-love-p ()
"Returns non-nil if the current project is a love project."
(doom-project-has! (and "main.lua" "config.lua")))
(set! :build 'run 'lua-mode #'+lua/run-love :when (+lua-love-p))
(set! :build 'build-project 'lua-mode #'+lua/build :when (+lua-love-p))
(set! :build 'generate-docs 'lua-mode #'+lua/generate-docs)
#+END_SRC
*** Code Evaluation
Run regions or entire buffers with [[https://github.com/syohex/emacs-quickrun][Quickrun]]. Output will be sent to a popup window.
Quickrun includes support for many languages, but occasionally, you'll find a language without support, such as [[https://crystal-lang.org/][Crystal]]. A "runner" can be defined like so:
#+BEGIN_SRC emacs-lisp
(set! :eval 'crystal-mode
'((:command . "crystal")
(:exec . "%c %s")
(:description . "Run Crystal script")))
#+END_SRC
A simpler version is simply to use the path to the binary:
#+BEGIN_SRC emacs-lisp
(set! :eval 'groovy-mode "groovy")
#+END_SRC
Or if you'd rather run an elisp command:
#+BEGIN_SRC emacs-lisp
(set! :eval 'emacs-lisp-mode #'+emacs-lisp-eval)
#+END_SRC

50
modules/lang/cc/README.org
View file

@ -1,29 +1,51 @@
* C/C++/Obj-C
* :lang cc
I use C/C++ mostly for developing games. To that end, this module leverages the
[[https://github.com/Sarcasm/irony-mode][irony plugin]] for auto-completion, eldoc documentation and syntax checking (with
flycheck).
This module adds support for the C-family of languages: C, C++, and Objective-C.
Though it provides Objective-C support, I don't use it except to inspect
generated glue code for iOS mobile apps.
+ Code completion (~company-irony~)
+ eldoc support (~irony-eldoc~)
+ Syntax-checking (~flycheck-irony~)
+ Code navigation (~irony~)
+ File Templates ([[../../feature/file-templates/templates/c-mode][c-mode]], [[../../feature/file-templates/templates/c++-mode][c++-mode]])
+ Snippets ([[https://github.com/hlissner/emacs-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/emacs-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/emacs-snippets/tree/master/c++-mode][c++-mode]])
+ Snippets ([[https://github.com/hlissner/emacs-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/emacs-snippets/tree/master/c++-mode][c++-mode]])
+ File templates ([[../../feature/file-templates/templates/c-mode][c-mode]], [[../../feature/file-templates/templates/c++-mode][c++-mode]])
#+begin_quote
C contends with Haskell and Ruby for my favorite language. It's hard to beat this combination of simplicity and power. I've used C for my work since 2009, and it (along with C++) is a personal favorite for game development (with SDL, SFML or, more recently, cocos2d).
** Installation
~irony-server~ is required to use irony-mode's features auto-completion (among
other things).
The module provides nominal support for Objective-C, which I really only use to inspect generated glue code for iOS mobile apps. Otherwise, I prefer Swift.
#+end_quote
To install it, run ~M-x irony-install-server~, which requires ~cmake~ and
~libclang~.
** Install
This module requires ~irony-server~ for most of its features, which depends on ~cmake~ and ~libclang~.
*** MacOS
Due to linking issues, MacOS users must compile irony-server manually:
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew install cmake
brew install llvm # 1gb+ installer: may take a while!
brew install llvm # 1gb+ installation! May take a while!
git clone https://github.com/Sarcasm/irony-mode irony-mode
mkdir irony-mode/server/build
pushd irony-mode/server/build
DEST="$HOME/.emacs.d/.local/$(hostname)/etc/irony-server/"
cmake -DCMAKE_INSTALL_RPATH_USE_LINK_PATH=ON \
-DCMAKE_INSTALL_PREFIX="$DEST" ../
cmake --build . --use-stderr --config Release --target install
install_name_tool -change @rpath/libclang.dylib \
/usr/local/opt/llvm/lib/libclang.dylib \
"$DEST/bin/irony-server"
# cleanup
popd
rm -rf irony-mode
#+END_SRC
*** Arch Linux
#+BEGIN_SRC sh :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --needed --noconfirm -S clang cmake
#+END_SRC
Then run ~M-x irony-install-server~ in Emacs.

42
modules/lang/go/README.org
View file

@ -1,14 +1,25 @@
* Go
* :lang go
Go support, including auto-completion, eldoc support (go-eldoc), REPL support,
refactoring commands, syntax-checking (flycheck), auto-formatting (gofmt) and
snippets (yasnippet).
This module adds [[https://golang.org][Go]] support.
+ [[https://golang.org][Homepage]]
+ [[https://github.com/hlissner/emacs-snippets/tree/master/go-mode][Snippets]]
+ Code completion (~gocode~)
+ eldoc support (~go-eldoc~)
+ REPL (~gore~)
+ Syntax-checking (~flycheck~)
+ Auto-formatting on save (~gofmt~)
+ Code navigation & refactoring (~go-guru~)
+ [[../../feature/file-templates/templates/go-mode][File templates]]
+ [[https://github.com/hlissner/emacs-snippets/tree/master/go-mode][Snippets]]
#+begin_quote
I have mixed feelings about Go. It's a decent compromise between C and higher-level languages. I like its simplicity and syntax (mostly), but it lacks /native/ support for certain luxuries I miss from other languages, like generics, optional arguments, and function overloading. You've got to learn to love ~interface{}~.
Still, Go has been a remarkably useful (and fast!) companion for a variety of small-to-medium backend web and CLI projects.
#+end_quote
** Install
To get started with Go, you need the ~go~ tool:
** Installation
*** MacOS
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew install go
@ -19,15 +30,20 @@ brew install go
sudo pacman --needed --noconfirm -S go
#+END_SRC
** Setup
You need to set up ~GOPATH~ before you can install lang/go's dependencies.
** Dependencies
This module requires a valid ~GOPATH~, and the following Go packages:
+ ~gocode~ (for code completion)
+ ~gore~ (for the REPL)
+ ~guru~ (for code navigation & refactoring commands)
+ ~gorename~ (for extra refactoring commands)
#+BEGIN_SRC sh
export GOPATH=~/work/go
go get -u github.com/nsf/gocode # completion
go get -u github.com/motemen/gore # REPL
go get -u golang.org/x/tools/cmd/guru # code navigation commands
go get -u golang.org/x/tools/cmd/gorename # refactoring commands
go get -u github.com/nsf/gocode
go get -u github.com/motemen/gore
go get -u golang.org/x/tools/cmd/guru
go get -u golang.org/x/tools/cmd/gorename
#+END_SRC

64
modules/lang/haskell/README.org Normal file
View file

@ -0,0 +1,64 @@
* :lang haskell
This module adds [[https://www.haskell.org/][Haskell]] support.
+ Code completion (~company-ghc~)
+ Look up documentation (~hoogle~)
+ eldoc support (~dante~)
+ REPL (~ghci~)
+ Syntax-checking (~flycheck~)
+ Code navigation (~dante~)
+ [[https://github.com/hlissner/emacs-snippets/tree/master/haskell-mode][Snippets]]
#+begin_quote
Haskell contends with C and Ruby as my favorite language. I don't think my Haskell code will ever save the world, but I'll reach for it when working on smaller projects and programming exercises (like projecteuler.com or exercism.io).
I'd love to incorporate more of it into my machine learning work, but Python and Julia hold that crown. For now.
#+end_quote
** Install
To get started with Haskell, you need:
+ cabal (the haskell package builder)
+ ghc/ghci (the compiler, syntax checker & repl)
*** MacOS
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew install cabal-install ghc
#+END_SRC
*** Arch Linux
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --needed --noconfirm -S cabal-install ghc
#+END_SRC
** Dependencies
This module requires the following ~cabal~ packages:
+ ~happy~ (required by ~haskell-src-exts~)
+ ~haskell-src-exts~ (required by ~ghc-mod~ & ~hoogle~)
+ ~ghc-mod~ (for auto-completion)
+ ~hoogle~ (for documentation lookup)
#+BEGIN_SRC sh
cabal update
cabal install happy haskell-src-exts ghc-mod hoogle
#+END_SRC
Ensure that ~\~/.cabal/bin~ is in ~PATH~:
#+BEGIN_SRC sh
# place this in your profile file, like ~/.bash_profile or ~/.zshenv
export PATH="~/.cabal/bin:$PATH"
#+END_SRC
** Troubleshooting
+ Stack users: if a ~dist/setup-config~ file exists in your project, [[ https://github.com/DanielG/ghc-mod/wiki#known-issues-related-to-stack][ghc-mod may
refuse to work]].
** Resources
Here are a few resources I've found indespensible in my Haskell adventures:
+ [[http://learnyouahaskell.com/][Learn you a haskell for great good]]
+ [[http://haskellbook.com/][Haskell Programming from first principles]]
+ [[https://github.com/krispo/awesome-haskell][Awesome Haskell]]: an extensive list of haskell resources

58
modules/lang/php/README.org Normal file
View file

@ -0,0 +1,58 @@
* :lang php
This module adds support for PHP 5.3+ (including PHP7).
+ ctags-based code completion (~company-php~ and ~phpctags~)
+ eldoc support (~ac-php~ and ~php-extras~)
+ REPL (~php-boris~)
+ Code refactoring commands (~php-refactor-mode~)
+ Unit-test commands (~phpunit~)
+ Support for ~laravel~ and ~composer~ projects (with project-specific snippets)
+ [[../../feature/file-templates/templates/php-mode][File templates]]
+ [[https://github.com/hlissner/emacs-snippets/tree/master/php-mode][Snippets]]
#+begin_quote
PHP was the first programming language I got paid to code in, back in the Cretaceous period (2003). I'm so, so sorry. All those programmers who inherited my earliest PHP work. I know you're out there, writhing in your straitjackets.
I suppose it's hip for programmers to projectile vomit to any mention of PHP, but they have good reason to. Not because it's /necessarily/ a bad language, and not /just/ because of a couple inconsistently ordered parameters, but because it's too easy to make junk with. You've heard the war stories.
Save a programmer today. Stop a friend from choosing PHP as their first language.
#+end_quote
** Install
To get started with PHP, you'll need ~php~ (5.3+) and ~composer~:
*** MacOS
PHP 5.5 comes prepackaged with newer versions of MacOS. These instructions are provided for reference:
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew tap homebrew/homebrew-php
brew install php71 # or php53, php54, php55
brew install composer
#+END_SRC
*** Arch Linux
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --needed --noconfirm -S php composer # or php53, php54, php55
#+END_SRC
** Dependencies
The features in this module optionally depends on the following php packages:
+ ~boris~ (REPL)
+ ~phpctags~ (better code completion)
+ ~phpunit~ (unit test commands)
#+BEGIN_SRC sh
composer global require \
d11wtq/boris \
phpunit/phpunit \
techlivezheng/phpctags
#+END_SRC
Ensure that ~\~/.composer/vendor/bin~ is in ~PATH~:
#+BEGIN_SRC sh
# place this in your profile file, like ~/.bash_profile or ~/.zshenv
export PATH="~/.composer/vendor/bin:$PATH"
#+END_SRC

54
modules/lang/rest/README.org
View file

@ -1,9 +1,51 @@
* REST
* :lang rest
On occasion I need to test REST APIs. I will, typically, open up an org buffer,
create a restclient source block and hack away. [[https://github.com/pashky/restclient.el][restclient-mode]] (and
[[https://github.com/iquiw/company-restclient][company-restclient]] for auto-completion) power this arcane wizardry.
This module adds [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] support.
Meanwhile, [[https://github.com/iquiw/company-restclient][ob-restclient]] integrates ~restclient-mode~ into org-babel.
+ Code-completion (~company-restclient~)
+ Code evaluation
+ org-mode: babel support (~ob-restclient~)
There are no external dependencies for this module.
#+begin_quote
~restclient-mode~ is tremendously useful for testing REST APIs. My workflow is to open an ~org-mode~ buffer, create a restclient source block and hack away. ~restclient-mode~ and ~company-restclient~ power this arcane wizardry.
#+end_quote
** Install
No additional setup required.
** Example
#+BEGIN_SRC restclient
GET https://jsonplaceholder.typicode.com/posts/1
#+END_SRC
#+BEGIN_EXAMPLE
#+RESULTS:
#+BEGIN_SRC js
{
"userId": 1,
"id": 1,
"title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
"body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}
// GET https://jsonplaceholder.typicode.com/posts/1
// HTTP/1.1 200 OK
// Date: Thu, 25 May 2017 13:43:42 GMT
// Content-Type: application/json; charset=utf-8
// Content-Length: 292
// Connection: keep-alive
// Set-Cookie: __cfduid=d3484257c800700f9882305963fa9d5d91495719822; expires=Fri, 25-May-18 13:43:42 GMT; path=/; domain=.typicode.com; HttpOnly
// X-Powered-By: Express
// Vary: Origin, Accept-Encoding
// Access-Control-Allow-Credentials: true
// Cache-Control: public, max-age=14400
// Pragma: no-cache
// Expires: Thu, 25 May 2017 17:43:42 GMT
// X-Content-Type-Options: nosniff
// Etag: W/"124-yiKdLzqO5gfBrJFrcdJ8Yq0LGnU"
// Via: 1.1 vegur
// CF-Cache-Status: HIT
// Server: cloudflare-nginx
// CF-RAY: 3648ecd7ef833d0d-CPH
// Request duration: 0.347179s
#+END_SRC
#+END_EXAMPLE

40
modules/ui/doom-modeline/README.org Normal file
View file

@ -0,0 +1,40 @@
* :ui doom-modeline
This module customizes the Emacs mode-line.
The DOOM modeline was designed for minimalism, and offers:
+ A match count panel (for ~evil-search~, ~iedit~ and ~evil-substitute~)
+ An indicator for recording a macro
+ Local python/ruby version in the major-mode
+ A customizable mode-line height (see ~+doom-modeline-height~)
+ An error/warning count segment for flycheck
[[/../screenshots/ml.png]]
[[/../screenshots/ml-search.png]]
[[/../screenshots/ml-subst.png]]
[[/../screenshots/ml-macro.png]]
[[/../screenshots/ml-version.png]]
[[/../screenshots/ml-errors.png]]
** Install
This module requires the fonts included with ~all-the-icons~ to be installed.
Run ~M-x all-the-icons-install-fonts~ to do so.
** Extracting my modeline
Some might want my modeline without the DOOM config altogether. I've taken some care to make this as easier for you.
Here is what you must do:
+ Ensure [[https://github.com/bbatsov/projectile][projectile]] and [[https://github.com/domtronn/all-the-icons.el][all-the-icons]] are installed
+ Ensure ~projectile-mode~ is enabled
+ Ensure the fonts included with ~all-the-icons~ are installed (~M-x all-the-icons-install-fonts~)
+ Replace ~def-package!~ calls with ~use-package~
+ Replace ~doom-project-root~ calls with ~projectile-project-root~
And you /should/ be good to go. As I have never used this out of my config I can't guarantee immediate success, but I'd be happy to help you out. File an issue.
** Troubleshooting
*** Where are my minor-modes?
I didn't need it, so I removed it. I wrote ~doom/what-minor-mode~ in the rare case I needed to investigate the currently active minor modes however.

27
modules/ui/doom/README.org
View file

@ -1,26 +1,33 @@
* DOOM
* :ui doom
DOOM's look is loosely inspired by Atom's One Dark theme. I've my [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]]
plugin to thank for bringing it to Emacs.
This module modifies Emacs' user interface.
On top of that, it uses:
DOOM's look is loosely inspired by Atom's One Dark theme, and is largely contained in the [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]] plugin.
+ [[https://github.com/mozilla/Fira][Fira Mono]] (font)
+ [[https://github.com/rolandwalker/nav-flash][nav-flash]]: blinks the current line when jumping large distances, to help keep
track of the cursor.
By default, this module uses:
+ [[https://github.com/mozilla/Fira][Fira Mono and Fira Sans]] (fonts)
+ [[https://dejavu-fonts.github.io/][DejaVu Sans Mono]] (font, for displaying unicode characters)
+ [[https://github.com/rolandwalker/nav-flash][nav-flash]]: blinks the current line when jumping large distances, to help keep track of the cursor.
+ ~hideshow~, modified to use a nicer folded-region indicator.
+ Custom fringe bitmaps for ~git-gutter-fringe~ (thin bars)
** Installation
** Install
[[https://github.com/mozilla/Fira][Fira Mono]] is this module's only dependency (if you want to use it).
*** MacOS
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew tap caskroom/fonts
brew cask install font-fira-mono
brew cask install font-fira-{sans,mono} font-dejavu-sans
#+END_SRC
*** Arch Linux
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --noconfirm --needed -S ttf-fira-mono
sudo pacman --noconfirm --needed -S ttf-fira-{sans,mono} ttf-dejavu
#+END_SRC
** Troubleshooting
*** Strange font symbols
If you're getting strange unicode symbols, that is likely ~all-the-icons~ doing (caused by other UI modules, specifically [[../doom-modeline][doom-modeline]] and [[../doom-dashboard][doom-dashboard]]).
You must install the fonts included with ~all-the-icons~ with: ~M-x all-the-icons-install-fonts~.