README.org

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