README.org

   1 * Readme for org2blog/atom
   2 ** Headers
   3 *** Purpose
   4
   5 To contain user docs for org2blog/atom
   6
   7 *** State
   8
   9 ** What it is
  10 An elisp package that lets you post from org-mode to Blogger and other
  11 blogs that use the Atom API
  12
  13 Entry points are:
  14  * org2blog/atom-post
  15  * org2blog/atom-dir-add-new-photos
  16
  17
  18 ** How to install it
  19
  20  * Install its dependencies
  21    * Install org-mode
  22    * Install g-client
  23      * This will require
  24        * org-mode
  25        * xsltproc (Or customize for another XSLT processor)
  26        * curl
  27    * Install tinydb
  28
  29  * Install org2blog/atom itself
  30    * If you have elinstall, just load do-elinstall.el (It's a
  31      script)  It will install.
  32    * If you use `my-site-start.el', you can just symlink
  33      "loaddefs.el" into your ~/.emacs.d/site-start.d/.  Give it a
  34      name like 30org2blog/atom.el
  35    * Failing that, have your .emacs load "subdirs.el".  Be sure to
  36      tell it the path, because load-path won't be set up yet.
  37    * If you don't have the patched g-client, apply the diff to g-client
  38
  39  * Configure it.
  40
  41    This is still fluid; g-client always was a little obscure to
  42    configure.  I've made it more automatic, but it could still be
  43    easier.
  44
  45    * Optionally, customize `g-user-auth-function'
  46      * If you have my library "password.el"
  47        * customize `g-user-auth-function' to
  48          : org2blog/atom-password-get-uid+pass
  49        * Call
  50          : M-x tehom-password-create
  51          and point it towards your Blogger account (or any other blog
  52          host that uses Atom API)
  53
  54      * For other password libraries, you may have to write some code
  55        to make them work together.
  56      * Otherwise, it will
  57    * You can also customize `org2blog/atom-l2r-alist-file' but you don't
  58      need to.
  59      * The default may require ~/.emacs.d/ to exist, I forget, but it
  60        probably already exists.
  61
  62 ** How to use org2blog/atom                                                 :userdoc:
  63  * Have an account on the blog
  64
  65  * Write a blog post as an org file
  66
  67    * You can use the usual org export file properties, such as #+AUTHOR:
  68      and #+TITLE:
  69    * You can use the file property "#+BLOGLABELS:" to set labels for
  70      the blog post.
  71
  72  * In that org buffer, command:
  73    : M-x org2blog/atom-post
  74    * That will put you in a gclient gblogger buffer with the post all
  75      set up.  It should be ready to go, but you can inspect it
  76      anyways.
  77    * When you're satisfied,
  78      : C-c C-c
  79    * It will post to blogger without further intervention.
  80    * It will capture a mapping from the local filename to the remote
  81      URL, so if you make other posts that link to it (the local file),
  82      they will point correctly to it (the url of the respective blog
  83      post)
  84      * The same works for photos, as long as org2blog/atom is loaded when
  85        they are uploaded.
  86
  87 ** Changes to g-client
  88  * User-visible changes
  89    * Some automatic capture of data, by only these interface functions:
  90      * gphoto-feeds
  91      * gphoto-photo-add
  92      * gblogger-blog
  93      * gblogger-new-entry
  94    * Changed gphoto-photo-add to ask for an album name from the list
  95      of albums, not an album id number.
  96    * Added a more flexible way of getting authentication:  Just
  97      customize (new variable) `g-user-auth-function'
  98    * Hooks
  99      * `g-app-afterpost-hook' which should be a function taking 2 args:
 100        * The source filename
 101        * The remote url
 102    * gphoto treats non-jpgs
 103      * Can find them in directories
 104      * (Forthcoming) Sends the right Content-Type for them.
 105      * Uses (both emacs-bundled packages) `image' and `image-file' to
 106        know about image file types.
 107    * g-load-defs.el now can be used as a symlink with my-site-start,
 108      because it knows its real location.
 109  * Internal additions:
 110    * Added optional arguments to some interfaces
 111      * Mostly to pass storers around
 112        * g-app-send-buffer
 113        * g-app-view
 114    * Added internal variables
 115      * To hold captured data
 116        * gphoto-album-list
 117        * gphoto-user-api-location
 118      * To name new XSL scripts
 119        * g-xsl-blogpost->url
 120        * g-xsl-photopost->url
 121        * g-xsl-feed->albums
 122      * To hold a buffer-local storer until g-app posts
 123        * g-app-storer
 124    * Many commands associated with capturing data
 125      * gblogger-blog-assign-data
 126      * gphoto-feeds-assign-data
 127      * g-app-setup-capture
 128      * g-util-capture-x
 129      * g-util-capture
 130    * Created some convenience functions because I found myself
 131      repeating code:
 132      * g-app-shell-command
 133      * g-app-build-command
 134      * g-app-build-storer
 135      * g-app-setup-posting
 136      * g-app-succeeded
 137      * g-display-common
 138    * Changed g-auth to use customizable variable
 139      `g-user-auth-function' for initial authentication.
 140      * Added g-user-default-auth-function, that variable's default
 141        value.
 142
 143
 144 ** Troubleshooting
 145
 146 *** Errors
 147
 148  * "Requires a different version of org-mode.  See README.org"
 149
 150    * You're using an old version of org-mode.  It's probably best to
 151     just upgrade.