#+MACRO: version 0.1
#+MACRO: versiondate 16 November 2014
#+MACRO: updated last updated {{{versiondate}}}

#+TITLE: SX: A StackExchange Client (v{{{version}}})
#+DATE: 16 November 2014
#+AUTHOR: @@texinfo:@url{@@www.github.com/vermiculus/stack-mode@@texinfo:}@@
#+LANGUAGE: en

#+OPTIONS: ':t toc:t

#+TEXINFO_FILENAME: sx.info
#+TEXINFO_HEADER: @syncodeindex pg cp

#+TEXINFO_DIR_CATEGORY: Texinfo documentation system
#+TEXINFO_DIR_TITLE: SX: (StackExchange Client)
#+TEXINFO_DIR_DESC: A StackExchange client for Emacs

#+TEXINFO_PRINTED_TITLE: SX: A StackExchange Client
#+SUBTITLE: for version {{{version}}}, last updated {{{versiondate}}}

* Copying
  :PROPERTIES:
  :COPYING:  t
  :END:

This manual is for SX (version {{{version}}}, {{{updated}}}), a
StackExchange client for Emacs.

Copyright © 2014 Free Software Foundation, Inc.

#+BEGIN_QUOTE
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, with no Front-Cover Texts,
and with no Back-Cover Texts.  A copy of the license is included in
the section entitled "GNU Free Documentation License".
#+END_QUOTE

* Introduction
SX is a StackExchange client for Emacs.  This means that it supports
many of the same features that the official web interface does, but in
a way that is /specialized/ for Emacs:

- question browsing for any site on the network
- asking, answering, and commenting
- advanced searching and filtering
- offline archiving
- inbox notifications
- ...

All of these features are implemented in a way that makes sense with
Emacs conventions.  Of course, the core convention of Emacs is
arbitrary customizability -- [[#hooks][hack away]]!

* Basic Usage
** Authenticating
Use ~sx-auth-authenticate~.  Calling this function will open up a
webpage on StackExchange that will prompt you to authorize this
application.  Once you do this, StackExchange will redirect you to our
own authorization landing page.  This landing page will prominently
display your access token.  (This is /your/ token -- keep this
private!)  Enter this token into Emacs.  Emacs will set and save it to
a cache file.

** Browsing Questions
To browse a list of questions retrieved from the site, use
~list-questions~.  This pulls the first page of questions from the
current site and displays them in a list.  Refresh the page with =g=,
use =n= and =p= to navigate without viewing the question, =j= and =k=
to do the same /with/ viewing the question, and =RET= to visit the
question at point.

* List of Hooks
  :PROPERTIES:
  :CUSTOM_ID: hooks
  :END:

# Do not list internal hooks.  While they are useful, they should be
# used only by contributors.

- ~sx-init-hook~ :: Run when ~sx-initialize~ is called.

* About this Document
This document is maintained in Org format.  Updates to the source code
should almost always be accompanied by updates to this document.  Some
distinctions are made which may not be apparent when viewing the
document with Info.

** Markup Conventions
Markup is used consistently as follows:

- packages :: =package.el=
- keybinding :: =C-x C-s= (use ~kbd~ format)
- values :: =value=
- symbols :: =symbol=
- functions :: ~function~

To make the Info export readable, lists and source code blocks are
separated from body text with a blank line (as to start a new
paragraph).

** Document Attributes
Attributes should be given in uppercase:

#+BEGIN_SRC org
  ,#+BEGIN_SRC elisp
    (some elisp)
  ,#+END_SRC
#+END_SRC

** Source Code Blocks
The language for Emacs Lisp source code blocks should be given as
=elisp= and its content should be indented by two spaces.  See
~org-edit-src-content-indentation~.

* COMMENT Local Variables
#  LocalWords:  StackExchange SX inbox sx API url json inline Org
#  LocalWords:  Markup keybinding keybindings customizability webpage

# Local Variables:
# org-export-date-timestamp-format: "$B %e %Y"
# End: