Skip to content

Latest commit

 

History

History
206 lines (170 loc) · 7.83 KB

sx.org

File metadata and controls

206 lines (170 loc) · 7.83 KB
Raw

SX: A StackExchange Client (v{{{version}}})

Copying

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

Copyright © 2014-2018 Free Software Foundation, Inc.

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”.

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 – 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

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 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 elisp
  (some elisp)
#+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).