### Archive

Archive for the ‘Emacs’ Category

## Set up a website using Emacs’ Org Mode

Recently I decided that maintaining my homepage in HTML was getting too laborious: the primary problem was things like lists and hierarchies. I have used Emacs’ Org Mode for my daily agenda for almost five years, and decided that it was the right tool for organizing these structures. Org Mode allows you to view “your life in plain text,” which is, of course, the most versatile way to do so. What Org can also do is export your hierarchical documents to HTML, LaTeX and many other formats (including formatted ascii, which is very nice). Along with this is the feature org-publish that uses Tramp to transfer a set of exported HTML files (and other files) to another location.

## Configuring org-project-alist

Read the Org Manual’s section on org-publish: you can find a simple example there. A single variable called org-publish-project-alist’ configures all the stuff you need to publish an entire website. Here’s mine:

(setq org-publish-project-alist
'(("mysite"
:base-directory "~/Documents/web/"
:base-extension "org"
:recursive t
:section-numbers nil
:table-of-contents nil
:publishing-directory "/ssh:joel@example.org:~/public_html"
:style "")
("imgs"
:base-directory "~/Documents/web/imgs/"
:base-extension "jpg\\|gif\\|png"
:publishing-directory "/ssh:joel@example.org:~/public_html/imgs"
:publishing-function org-publish-attachment
:recursive t)
("etc"
:base-directory "~/Documents/web/"
:base-extension "css\\|bib\\|el"
:publishing-directory "/ssh:joel@example.org:~/public_html"
:publishing-function org-publish-attachment)
("docs"
:base-directory "~/Documents/web/docs/"
:base-extension "html\\|tex\\|bib"
:publishing-directory "/ssh:joel@example.org:~/public_html/docs"
:publishing-function org-publish-attachment)
("thewholedamnshow" :components ("mysite" "imgs" "etc" "docs"))))


After a few days of having this in my .emacs I decided this needed its own file, which I called “project.el” and placed in the home directory of my project.

Each one of the members of this list is a “project.” Projects can include other projects by using the “:components” property. Suppose my website’s files are in the directory “~/Documents/web/”. This is where I keep the actual org-mode files, css files and any other files I want to publish. The property “:publishing-directory” puts the exported files in the specified location, which is a tramp url. The trick is really the property “:publishing-function,” which tells org-publish’ how to treat the files. If left blank, this will translate the files into HTML. For .css files and other stuff you might link to (e.g. my .bib or tex .files, or images) you can use the function org-publish-attachment’, which does no translation.

The crucial part of this variable is then the last “project,” which has only a “:components” property. This includes all the other projects, and hence when I publish “thewholedamnshow” using org-publish’ my entire set of files is exported and uploaded.

## Directory Structure

Now I have all the sources for my website in one directory. Before I had used a highly hierarchical setup that made links very complicated. After realizing that I didn’t have actually that much content, I now have all the org files in the toplevel directory, with two subdirectories: one for images and one for special documents that are not in Org Mode. These are essays or LaTeX documents that are already finished works and I do not expect to change them.

I keep all the Org Mode source files in Bazaar. This greatly simplifies things. With project.el included along with the website, I can work on this on any machine as long as I evaluate that variable before I upload using org-publish’.

A huge advantage is that now everything (including my CV, publications, and my ever-expanding academic FAQ) is in Org Mode. This means that changes are super-easy, even structural changes that I wouldn’t have attempted with HTML. So now when I need to update my CV, or add an FAQ, all I do is edit in Org Mode, something that I am very familiar with because I do it most of the day every day. I actually just categorized my FAQ using Org Mode in a matter of minutes. Linking with Org Mode is also incredibly easy, and the exporter knows how to handle links to files, headlines within files and internet urls. Also, since these documents are now in Org Mode, if someone wants a PDF version, all it takes is a few keystrokes to produce it.

Other huge advantages include features specific to Org Mode’s HTML exporting functions: Org Mode includes an option to specify MathJax display of mathematics: you enter LaTeX, publish with org-publish’ and MathJax produces copy-and-pasteable MathML or LaTeX, and displays everything correctly according to the viewer’s browser. Javascript-controlled TOC views can make a page into an Emacs Info-style document. I chose this for my FAQ, since some of the answers were getting quite lengthy.

The weirdest thing is how easy this is once I figured it all out. After only a week of tinkering, I now have a website that I can update or make major changes to in a matter of minutes. It looks better, is easier to maintain and easier to configure.

Categories: Emacs, Web Tags: , , , ,

## Emacs : eldoc mode and c-eldoc mode (via Passing Thoughts)

July 9, 2010 1 comment

Here’s an excellent Emacs minor mode that I discovered last week, as did our friend at Passing Thoughts:

eldoc mode as the name suggests provides documentation for Elisp files. This is a very useful and cool mode and shows the function signature in the mode-line when your cursor is on a particular function.  It also provides info on the variables. Check out the screen-shots below. To start eldoc mode, add the following to your .emacs file ;;Turn on documentation in elisp mode (add-hook 'emacs-lisp-mode-hook '(lambda () (turn-on-eldoc-mode))) c-eldoc … Read More

Categories: Emacs, Programming, Tools

## Emacs Auto-complete Mode

I’ve just discovered a new add-on for Emacs called auto-complete-mode. After watching the video I was skeptical: I thought “this is going to get annoying really fast. However, after giving it a quick try, it is pretty cool. I think it will be especially useful in programming modes, since it presents your own symbol values from the current buffer as completion values. Also, auto-complete-mode only tries to complete if you pause typing. You can also bind a specific key (the author recommends M-TAB) to initiate auto-completion.

So I just typed “auto-completion” and the first choice that came up when I paused after “auto-compl” was “auto-complete-mode,” but then I hit TAB after the menu comes up and “auto-completion” is there now too. In other words, auto-complete-mode is smart: it learns.

Categories: Emacs, Tools Tags:

## Sacha Chua on Automation

Read this bit from Sacha Chua about automation. Sacha is one of those entertaining hackers who seems to really “get it.” I really enjoy reading her stuff, most of which is really useful Emacs tips.

Categories: Emacs, Programming Tags: