Tuesday, December 19, 2006

Vim-BloggerBeta Plugin Release

It turns out I'm not really doing any more modifications to this plugin code because it is working fine for me. I decided then, instead of just sitting on it maybe I should share it! So here it is... Keep in mind that this no doubt a little rough around the edges as far as usability goes. I'll do my best to describe the plugin here.

Pre-requisites

First of all, this plugin requires Python support to be compiled into Vim. As in, if you do a :version in Vim and do not see +python in the output, this plugin will not work.

Also, you will need to provide some information for the plugin in the form of three variable settings. The plugin needs to know your blog URL, your Gmail login, and your Gmail password. The variable names for these are g:Blog_URI, g:Gmail_Account, and g:Gmail_Password respectively. Given that some of these variables contain sensitive information, you probably want to take some steps to keep them somewhat private. I often put my ~/.vimrc online for others to read, so putting them in there is a bad idea. Instead, I created a ~/vim/plugin/creds.vim file, made it readable by my user only, and stuck the info in there. Keep in mind, however, that these are global variables and as such, will be available to all scripts that you run. Also, someone could quite easily get those values by typing :echo g:Gmail_Password in your vim session for example. If you have some ideas about how to keep this stuff more secure I'd be interested in hearing about them. For now, however, you've been warned :).

Installation

The plugin comes in the form of a tarball. Inside this tarball are five files.

  • plugin/blogger.vim: This script provides a single command called :Blog that simply opens a temporary blogger file which in turn sources the blogger.vim filetype plugin.
  • ftplugin/blogger/blogger.vim: This is the filetype plugin that contains the rest of the plugin's functionality.
  • syntax/blogger.vim: The included syntax file provides highlighting to buffers with the filetype blogger. It is essentially the Markdown syntax file found here with a few vim-blogger specific additions.
  • ftplugin/blogger/markdown.py: This is the Python module found here that the plugin uses to convert Markdown to HTML.
  • ftplugin/blogger/html2text.py: The Python module found here which the plugin uses to convert HTML back to Markdown.

To install, you just need to untar this tarball inside your ~/.vim/ directory. All should fall into the appropriate locations. Next, you probably want to make Vim set the filetype to blogger whenever it opens an appropriate file. To do this, put this line in your ~/.vim/filetype.vim file:

autocmd! BufRead,BufNewFile     *.blogger   setf blogger

This will set the filetype accordingly whenever you open a file with the blogger extension, hence sourcing the ftplugin and syntax files.

General Post Form

In a Vim buffer, a post generally looks like this screenshot:

post-screenshot

The first line in the buffer is the post subject. The last line contains the keyword @@LABELS@@ followed by a comma separated list of labels for this post. The stuff in the middle is the post body. One variation of this is if you are editing a post that was already published. In this case, the first line will be of the form @@EDIT#@@. This is put there by the plugin, and used by the plugin. You probably don't want to delete it. In this case, the post subject will be the second line in the buffer.

Usage

There are several commands included with the plugin. I'll briefly describe each of them here.

Retrieving Your Most Recent Posts

Running the :BlogIndex command will display a list of your most recent blog posts. By default, it will only display the last five to keep the list manageable, but it can take an integer argument if you would like to change that. A numbered list of posts is shown. To begin editing one of these posts, simply type the post number and press Enter. This list also contains posts that you have saved as drafts. Drafts are distinguishable by the word **DRAFT** beside the post subject.

Retrieving Your Posts By Label

If you would like to see a list of blog posts by label, run the :BlogQuery command with a comma separated list of labels that you would like to query for. Again, a numbered list is returned. To edit a specific post, type the appropriate number and press Enter.

Publishing or Updating a Post

The :BlogPost command can be used to either publish a new post or to update an existing post. If the current post is marked as being a draft, then the draft status is removed and the post is published. Upon successfully issuing this command, it will appear in the list displayed by the :BlogIndex command.

Saving a Post as Draft

Just like the :BlogPost command described above, the :BlogDraft command sends your post to the Blogger server, only this time it is marked as a draft. The post will not appear in your blog, but will appear in the plugin's index (displayed with the :BlogIndex command) as a **DRAFT** post.

Deleting a Post

To delete a post, run the :BlogIndex command to get a list of posts, choose the post from the list as if you were going to edit it, and issue the :BlogDelete command. The plugin will ask the user for confirmation, and upon responding with "yes" (nothing else will do), the post is deleted from your blog.

Using or Not Using Markdown

One of the things I like about this plugin is that I can use Markdown syntax to write my posts. This text is then converted by the plugin to HTML, and sent to the Blogger servers as a post. If I then want to edit that same post, the HTML code is retrieved from the server, converted back to Markdown, and made available for me to edit. Some people, however, will inevitably prefer to just compose their posts in straight HTML. For these people, there is a global variable called g:Blog_Use_Markdown which enables this portion of the plugin. To reduce confusion for the people who do not know about this feature of the plugin I've made this variable default to False. Therefore, if you want to use the Markdown stuff, put let g:Blog_Use_Markdown = 1 in your ~/.vimrc file.

Conclusions

Keep in mind that this plugin was written to scratch a particular itch of mine that was caused by slow web interfaces with a cruddy editor in a slow web browser on a slow laptop. I've been using it to make all of the posts that you see on this blog. However, it may or may not do what you expect when you expect it. Hopefully there are few actual errors, but I'm sure there will be some as I've not fully tested the plugin under every scenario. If you do find a bug or need help getting it to work, email me at my Gmail account, username "dcraven". General comments are welcomed here on the blog.

9 comments:

  1. Thx a lot; it's great!
    Have used this just now.

    ReplyDelete
  2. Thanks a lot.. Works great with the markdown and with :setlocal spell spelllang=en_us enabled to spell check on the fly, blogging just got a lot better.

    ReplyDelete
  3. Wonderful! This script does exactly what I always wanted!

    ...except... that it seems to have a problem with not-ascii encodings. I did a google search and found out that the problem is actually a feature in gdata module. Although all google tools use UTF-8 as default encoding, the gdata seem to prefer 7 bit ASCII :) The gdata developpers have been notifed (by someone else) and seem inclined to do the correction in gdata's code.

    For the time begin, I propose a workaround for your script. I write portuguese and japanese in my blog and by changing the following lines in "blogger.vim", I got the script to work perfectly.

    lines 206 and 208:
    replace:
    BLOGGER_POSTS[i]['title']
    with: BLOGGER_POSTS[i]['title'].encode('UTF-8')

    line 237
    replace:
    str(title)
    with:
    str(title.encode('UTF-8'))

    line 247
    replace:
    str(content)
    with:
    str(content.encode('UTF-8'))

    ReplyDelete
  4. When using :BlogDraft, Blogger shows a new draft post with the correct title but no content. Is there debugging of some sort that I can enable to see what's happening behind the scenes?

    ReplyDelete
  5. Thank you. I have a similar one for Livejournal( its called pyljvim). I was looking for blogger equivalent and found yours. Yours is feature rich and seems very complete.
    Good Work, Fella.

    ReplyDelete
  6. Hello,
    From what I can see it's a while ago since you created this script. Anyway it seems to be what I want, but the download link is not working, can someone help me please?

    ReplyDelete
  7. Hi,
    your link is dead now.
    Could you post in another place ?

    ReplyDelete
  8. The link is alive but returns a empty file.

    ReplyDelete
  9. http://arker.homelinux.org/files/vim-blogger/vim-blogger.tar.gz is not downloadable. Is this plugin still usable with the new blogger engine?

    ReplyDelete