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
|
#+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:
|
