#+MACRO: version 0.2
#+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/sx.el@@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

** Activation

If you install ~SX~ with ~package-install~, you should have every
needed command properly autoloaded.  If you install it manually,
require the ~sx-load~ file to make sure everything is correctly
loaded.

** 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
~sx-tab-frontpage~.  This queries for a site, pulls the first page of
questions for that site, and displays them in a list.  Alternatively,
use any of the other ~sx-tab-~ commands.

- Refresh the page with =g= or by scrolling past the top.
- Use =n=, =p=, =N=, =P= to navigate without viewing the question.
- =j=, =k=, =J=, =K= to do the same /with/ viewing the question.
- =RET= to open the question with Emacs.
- =v= to visit it with a browser.

Scrolling past the bottom of the list fetches more questions.

* 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.
- ~sx-compose-before-send-hook~ :: Run before POSTing to the API from
     a buffer in ~sx-compose-mode~.  If any of the functions in this
     hook, return nil, the transaction is canceled.
- ~sx-compose-after-send-functions~ :: Run after POSTing to the API
     from a buffer in ~sx-compose-mode~, if the transaction was
     successful.

* Contributing
Contributions, be them to the code or to this document, are very much
welcome.  Both of these can be found at [[github.com/vermiculus/sx.el][the GitHub repository]].  The
easiest way to contribute is to clone it, make your changes, and
submit a pull request.  If you prefer, you can also email a patch of
your changes to one of the authors or maintainers listed in the header
comments.  But please, when you do, heed the following conventions.

1. Contributions to the code which change or add user-facing
   functionality should be accompanied by updates to this document.
2. Both in code and in this document, sentences should end in double
   space.

** Contributing to this Document
This document is maintained in Org format.  Updates to the source code
should be accompanied by updates to this document when user-facing
functionality is changed.

Note that 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~.

** Contributing to the Code
Contributing to the code should be fairly straightforward.  Each file
has a descriptive header explaining its purpose.  Still, to help you
find your way around, we describe below the current project
structure. This list is very loosely ordered form low to high-level.

- ~sx.el~ :: Utility functions used throughout the
             package. Essentially every file indirectly requires this
             one. If you're adding a function that's used by different
             parts of the package, add it to this file.
- ~sx-time.el~ :: Similar to ~sx.el~, but only contains a few
                  time-related functions.
- ~sx-filter.el~ :: Handles retrieval of filters.
- ~sx-cache.el~ :: Saves and restores persistent data between
                   sessions.
- ~sx-button.el~ :: Defines all button types used throughout the
                    package. Currently used only by
                    ~sx-question-print.el~.
- ~sx-request.el~ :: Requests and url manipulation. Back-end used by
     ~sx-method.el~. It shouldn't be necessary to use the functions in
     this file outside ~sx-method.el~.
- ~sx-method.el~ :: Main interface for API method calls.
- ~sx-favorites.el~ :: Starred questions.
- ~sx-networks.el~ :: User network information.
- ~sx-site.el~ :: Browsing sites.
- ~sx-auth.el~ :: Handles user authentication.
- ~sx-question.el~ :: Base question logic. Holds several functions for
     retrieving questions and for processing retrieved
     questions. Doesn't do any sort of user interface, that is left
     for ~sx-question-list.el~ and ~sx-question-mode.el~.
- ~sx-question-list.el~ :: Major-mode for navigating questions list.
- ~sx-question-mode.el~ :: User interface for displaying a
     question. Creates the buffer and defines the major-mode.
- ~sx-question-print.el~ :: Populating the question buffer with
     content. Used by ~sx-question-mode.el~ to actually print the
     content of a question.
- ~sx-babel.el~ :: Font-locking code blocks printed by
                   ~sx-question-print.el~ according to the language.
- ~sx-compose.el~ :: Major-mode for composing questions and answers.
- ~sx-interaction.el~ :: Voting, commenting, and otherwise interacting
     with questions.
- ~sx-tab.el~ :: Functions for viewing different tabs.
- ~sx-load.el~ :: Load all files of the SX package.  Designed as an
                  easy way in for users who install the package
                  manually (since they don't have autoloads).

* 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"
# sentence-end-double-space: t
# End: