Merge pull request #77 from vermiculus/documentation

Documentation

1 files changed, 126 insertions, 0 deletions

diff --git a/sx.org b/sx.org
new file mode 100644
index 0000000..b646b2c
--- /dev/null
+++ b/sx.org
@@ -0,0 +1,126 @@
+#+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.
+
+* Contributing
+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~.
+
+* 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: