diff options
Diffstat (limited to 'sx.org')
| -rw-r--r-- | sx.org | 81 |
1 files changed, 77 insertions, 4 deletions
@@ -55,6 +55,14 @@ 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 @@ -67,7 +75,8 @@ 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. +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. @@ -86,8 +95,27 @@ Scrolling past the bottom of the list fetches more questions. # 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 cancelled. +- ~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. @@ -95,7 +123,7 @@ functionality is changed. Note that some distinctions are made which may not be apparent when viewing the document with Info. -** Markup Conventions +*** Markup Conventions Markup is used consistently as follows: - packages :: =package.el= @@ -108,7 +136,7 @@ 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 +*** Document Attributes Attributes should be given in uppercase: #+BEGIN_SRC org @@ -117,11 +145,56 @@ Attributes should be given in uppercase: ,#+END_SRC #+END_SRC -** Source Code Blocks +*** 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. Backend 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 |