1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
#+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 prominately
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.
- ~sx-init-hook~ :: Run when ~sx-initialize~ is called.
* Developer's Reference
Creating a logically consistent piece of software requires that all
developers know the patterns established and resources made available
to them. These sections hope to do just that.
** Caching
All cached data is stored in =sx-cache-directory=. This defaults to
=~/.emacs.d/.stackmode= where =user-emacs-directory= is =~/.emacs.d=.
Each piece of cached data is stored in its own file.
There are two main functions for interfacing with the cache system:
- ~sx-cache-get~ :: Gets a cached variable's value, setting it if it
does not exist. This function will, as a
side-effect, ensure that the cache file exists.
- ~sx-cache-set~ :: Sets a cached variable's value.
Each of these functions will ensure =sx-cache-directory= exists.
** Making API Requests
API requests are handled on three separate tiers:
- ~sx-method-call~ :: This is the function that should be used most
often, since it runs necessary checks (authentication) and
provides basic processing of the result for consistency.
- ~sx-request-make~ :: This is the fundamental function for
interacting with the API. It makes no provisions for 'common'
usage, but it does ensure data is retrieved successfully or an
appropriate signal is thrown.
- =url.el= and =json.el= :: The whole solution is built upon =url.el=
for making the request and =json.el= for parsing it into a
properly symbolic data structure.
When at all possible, use ~sx-method-call~. There are specialized
cases for the use of ~sx-request-make~ outside of =sx-method.el=, but
these must be well-documented inline with the code.
*** ~sx-request-make~
Requests are made by building a parameter string of the format
#+BEGIN_EXAMPLE
key=value&key=value
#+END_EXAMPLE
and appending it to a root and a method:
#+BEGIN_EXAMPLE
<root>/<method>?<parameters>
#+END_EXAMPLE
This works fine for 'GET' requests of the API, but will not work for
'POST'. A revised request system is being created that will support
both of methods.
** Working with Data
The API returns data in JSON format. When a method is called, the
response is enclosed in a 'wrapper' that includes various metadata:
- remaining requests for your quota
- if the response has been truncated
- etc.
When ~sx-request-make~ receives the response, it sets variables
related to the response (most notably the number of remaining
requests) and returns just the main content of the response. In order
to access this content, you could use a lengthy ~let~-binding or you
could use the ~sx-assoc-let~ macro. That is,
#+BEGIN_SRC elisp
(sx-assoc-let data
(some fancy .function with a .property
in 'data))
#+END_SRC
expands to
#+BEGIN_SRC elisp
(let
((.function (cdr (assoc 'function data)))
(.property (cdr (assoc 'property data))))
(some fancy .function with a .property
in 'data))
#+END_SRC
Use the following to highlight the special =.property= forms:
#+BEGIN_SRC elisp
#+END_SRC
* 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. Soem
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
# Local Variables:
# org-export-date-timestamp-format: "$B %e %Y"
# End:
|
