#+Title: SX -- Stack Exchange for Emacs

[[https://travis-ci.org/vermiculus/sx.el][https://travis-ci.org/vermiculus/sx.el.svg?branch=master]]
[[http://melpa.org/#/sx][file:http://melpa.org/packages/sx-badge.svg]]
[[http://stable.melpa.org/#/sx][file:http://stable.melpa.org/packages/sx-badge.svg]]
[[https://gitter.im/vermiculus/sx.el?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge][https://badges.gitter.im/Join Chat.svg]]
[[https://www.waffle.io/vermiculus/sx.el][https://badge.waffle.io/vermiculus/sx.el.svg]]

SX is a full-featured Stack Exchange mode for GNU Emacs 24+.  Using the official
API, it provides a versatile experience for the Stack Exchange network within
Emacs itself.

[[file:list-and-question.png]]

* Features
As always, =C-h m= is the definitive resource for functionality, but here are a
few highlights:
** Viewing Questions
*** Question Lists
View questions with one of the ~sx-tab-~ commands.  These translate roughly to
the different 'tabs' that you can view on the official site.  Implemented tabs
include:

- ~sx-tab-all-questions~      :: All questions.
- ~sx-tab-unanswered~         :: =u= Unanswered questions.
- ~sx-tab-unanswered-my-tags~ :: =U= Unanswered questions in your followed tags.
- ~sx-tab-featured~           :: =f= Featured questions.
- ~sx-tab-starred~            :: =*= Your starred questions.
- ~sx-tab-frontpage~          :: =h= The frontpage of the site.
- ~sx-tab-meta-or-main~       :: =m= Toggle between the meta and main sites.
- ~sx-tab-newest~             :: =n= Newest questions first.
- ~sx-tab-topvoted~           :: =v= Highest-scoring questions first.
- ~sx-tab-week~               :: =w= Hot questions of the week.

Inside SX buffers, you can switch to other tabs by typing =s= followed by the key
listed with the tab above.  You can also use ~sx-tab-switch~ (=s t=) to switch
between tabs with completion.  Each of these opens up a list of questions, and
you can further customize the ordering of the list with =O=.  Other keys
include:

- =n= and =p= :: Navigate the list.
- =j= and =k= :: Navigate while viewing the question in a separate buffer.
- =s s= :: Switch site.
- =v= :: Visit the ~thing-at-point~ in your browser.
- =w= :: Copy the ~thing-at-point~ (usually a link).
- =u= and =d= :: Upvote and downvote.
- =RET= :: Open the question buffer.

*** Questions and Answers
- =u= and =d= :: Upvote and downvote the question, answer, or comment at point.
- =a= :: Add an answer.
- =e= :: Edit the question or answer (or comment if it's yours; the usual rules
         apply)
- =*= :: Star the question.
- =K= :: Delete the question/answer/comment if you are able.
- =w= :: Copy code at point.

** Your Inbox
- ~sx-inbox~ :: View your inbox
- ~RET~ :: Visit inbox item

* Installation
SX is now available on MELPA!  Both the stable release and the development
version can be found there.  Install it via the Package Menu or just run
#+BEGIN_SRC text
M-x package-install RET sx RET
#+END_SRC

** Authenticating
If you are going to be doing any
asking/answering/commenting/upvoting/downvoting/ /etc./, you must use
~sx-authenticate~ to provide SX with an authentication token to act on your
behalf.

After authentication, you will be redirected to the project page.  This page
will prominently display your authentication token. *Keep this secret!* It's as
good as your password as far as StackExchange is concerned.  Copy and paste the
token into the prompt in Emacs.

#+BEGIN_QUOTE
SX will store this authentication token in plain text in the =sx= folder of
your =.emacs.d=.  Please take any and all steps necessary to protect the
security of your account.  This token is as good as a password.
#+END_QUOTE

** Sample Keybindings
*** With =use-package=
#+BEGIN_SRC elisp
  (require 'use-package)

  (use-package sx
    :config
    (bind-keys :prefix "C-c s"
               :prefix-map my-sx-map
               :prefix-docstring "Global keymap for SX."
               ("q" . sx-tab-all-questions)
               ("i" . sx-inbox)
               ("o" . sx-open-link)
               ("u" . sx-tab-unanswered-my-tags)
               ("a" . sx-ask)
               ("s" . sx-search)))
#+END_SRC
*** Standard (With Prefix Key)
Shamelessly stolen from [[http://endlessparentheses.com/sx-el-announcement-and-more-launcher-map.html][Endless Parentheses]].
#+BEGIN_SRC elisp
(define-prefix-command 'launcher-map)
(global-set-key (kbd "s-l") 'launcher-map)
(define-key launcher-map "qq" #'sx-tab-all-questions)
(define-key launcher-map "qi" #'sx-inbox)
(define-key launcher-map "qo" #'sx-open-link)
(define-key launcher-map "qu" #'sx-tab-unanswered-my-tags)
(define-key launcher-map "qa" #'sx-ask)
(define-key launcher-map "qs" #'sx-search)
#+END_SRC

* Contributing
Please help contribute!  Doing any of the following will help us immensely:
 - [[https://github.com/vermiculus/sx.el/issues/new][Open an issue]]
 - [[https://github.com/vermiculus/sx.el/pulls][Submit a pull request]]
 - [[https://gitter.im/vermiculus/sx.el][Suggest a package or library in our Chat on Gitter]] (or just hang out =:)=)
 - Spread the word!

For a better view of all of the open issues, take a look at our lovely [[http://www.waffle.io/vermiculus/sx.el][Waffle
board]].  Feel free to take the torch on anything in =backlog= or =ready=.  If you
have thoughts on any other issues, don't hesitate to chime in!

See also =CONTRIBUTING.org=.

* Resources
- [[http://www.gnu.org/software/emacs/][GNU Emacs]]
- [[https://api.stackexchange.com/docs][Stack Exchange API v2.2]]

** Icons
SX has no explicit /need/ for an icon, although standard SVG files
have been gathered in =resources/= if anyone would fancy a crack at
it.

- [[file:resources/emacs.svg][Emacs icon]]
- [[file:resources/stackexchange.svg][Stack Exchange icon]]
* COMMENT Local Variables
# Local Variables:
# fill-column: 80
# End: