== Getting _gocode_ based autocompletion working for Go in GNU Emacs

The existing guides and documentation for this are terrible and
incomplete for someone who is not already experienced with GNU Emacs
Lisp packages (which describes me), so here is what worked for me. I'm
going to assume that your _$GOPATH_ is _$HOME/go_ and that _$GOPATH/bin_
is on your _$PATH_.

.pn prewrap on

* get [[gocode https://github.com/nsf/gocode]] itself:
  >  go get github.com/nsf/gocode

  To work in GNU Emacs, _gocode_ needs an auto-completion package;
  it recommends [[auto-complete http://auto-complete.org/]], so
  that's what I decided to use. If you have that already you're done,
  but I didn't. At this point you might be tempted to go to [[the
  auto-complete website http://auto-complete.org/]] and try to follow
  directions from there, but you actually don't want to do this because
  there's an easier way to install it.

* The easiest way to install auto-complete and its prerequisites
  is through [[MELPA http://melpa.org/]], which is an additional package
  repo for Emacs Lisp packages on top of the default [[ELPA
  https://elpa.gnu.org/]]. To enable MELPA, you need to add a stanza
  to your _.emacs_ following its getting started guide, generally:

  >  (require 'package)
  >  (add-to-list 'package-archives
  >    '("melpa" . "https://melpa.org/packages/"))
  >  (package-initialize)

* make sure you have a _$HOME/.emacs.d_ directory. You probably do.

* (re)start Emacs and run M-x list-packages. Navigate to _auto-complete_
  and get it installed. If you're running GNU Emacs in X, you can
  just click on its name and then on the [Install] button; if you're
  running in a terminal window, navigating to each thing and then
  hitting Return on it does the same. This will install _auto-complete_
  and its prerequisite package _popup_, the latter of which is not
  mentioned on [[the auto-complete site http://auto-complete.org/]].

  It's possible to install auto-complete manually, directly from the
  site or more accurately from [[the github repo's release page
  https://github.com/auto-complete/auto-complete/releases]]. Do it
  from MELPA instead; it's easier and less annoying. If you install
  manually you'll have to use MELPA to install _popup_ itself.

* Set up the _.emacs_ stanza for gocode:

  >  (add-to-list 'load-path "~/go/src/github.com/nsf/gocode/emacs")
  >  (require 'go-autocomplete)
  >  (require 'auto-complete-config)
  >  (ac-config-default)

  This deliberately uses the go-autocomplete.el from _gocode_'s Go
  package (and uses it in place), instead of one you might get
  through eg MELPA. I like this because it means that if (and when)
  I update _gocode_, I automatically get the correct and latest
  version of its Emacs Lisp as well.

Restarting GNU Emacs should then get you autocompletion when writing
Go code. You may or may not like how it works and want to keep it;
I haven't made up my mind yet. Its usage in X appears to be pretty
intuitive but I haven't fully sorted out how it works in text mode
(the major way seems to be hitting TAB to cycle through possible
auto-completions it offers you).

(Plenty of people seem to like it, though, and I decided I wanted
to play with the feature since I've never used a smart IDE-like
environment before.)

See also [[Package management in Emacs: The Good, the Bad, and the
Ugly
http://batsov.com/articles/2012/02/19/package-management-in-emacs-the-good-the-bad-and-the-ugly/]]
and [[Emacs: How to Install Packages Using ELPA, MELPA, Marmalade
http://ergoemacs.org/emacs/emacs_package_system.html]]. There are
probably other resources too; my Emacs inexperience is showing here.

(As usual, I've written this because if I ever need it again I'll
hate myself for not having written it down, especially since the
directions here are the result of a whole bunch of missteps and
earlier inferior attempts. The whole messy situation led to [[a
Twitter rant https://twitter.com/thatcks/status/640015866290118656]].)