README.org

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