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’.

Advantages

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.

I don’t know if Mark Zuckerberg is a bad person

Since writing about how Time chose Mark Zuckerberg as Person of the Year I’ve gotten lots of traffic from people searching Google asking if Mark Zuckerberg is a bad person. I didn’t understand why people were asking Google, but last night I watched The Social Network and I realized that a major theme of the film is Mark Zuckerberg’s character. In rather artful form, the film leaves it an open question, but I can see how it would get people thinking. Surprisingly (and not) the film focuses on the legal question, and the moral questions that the legal questions are proxies for, as the meat of the plot. Despite that focus, it includes a lot of realistic dialog (“I need a dedicated Linux box running MySQL…”), and even realistic computer screens (KDE).

I was mainly interested in seeing the film for the music composed by Trent Reznor, but I saw the same themes coming up that plague our society and indeed fuel Facebook’s traffic today. The point of the film is basically that Mark Zuckerberg is a “post-modernist demon” who does what he does because he just loves hacking and wants to keep doing it, but that means he screws his friends and pisses off some wealthy meatheads in the process. I think that overall this is a good film and everybody should see it, if only for the problems that it demonstrates about our society.

I really liked that the film incorporated enough real programming. To hear someone mention Emacs in a major motion picture was just irresistible. As I said, the dialog was realistic: the characters discuss algorithms, they mention software by name (I heard Python, MySQL, Perl, Mozilla, Apache, …), and they discuss the values associated with the internet. I loved the photography. I LOVED the portrayal of Larry Summers. What was weird was

• Sean Parker (played by Justin Timberlake, and well done Mr. Timberlake!) refers to Napster as a “downloading and sharing site” when it was no such thing; this was the most unbelievable piece of dialog in the film; people keep saying Napster was a “downloading site,” continuing to demonstrate how they just don’t get it
• The sound was badly mixed; I’m trying to attribute this to my bad speakers, but in some places there was just too much noise in the background
• When the Winklevoss twins ask Zuckerberg why he “uploaded for free” his “MP3 player” he just shrugs his shoulders: this is totally out of character. He should have said “I was done with it,” or “I thought people shouldn’t have to pay for it, I just did it for fun.” That’s what somebody who “doesn’t care about money” would have said. This part of the character was poorly defined

Come to think of it, except for his gusto for work, very little about Zuckerberg’s character is well-defined. The movie totally glosses over how Zuckerberg himself came from a wealthy background, and was extraordinarily privileged (news flash: most people who make lots of money already have lots of money) — he wasn’t that different from other Harvard students. None of it resolves or even comments on whether he is a bad person. It doesn’t matter. Whether the real Mark Zuckerberg is a bad person doesn’t matter either. I don’t care if he is, I don’t know if he is. Again, it doesn’t matter. It doesn’t matter if Facebook is a bad company; it doesn’t matter if Facebook provides a good product. I don’t think you should use Facebook, but it’s your choice if you want to. I don’t think you’re immoral for using Facebook. I don’t think that Facebook (the corporation) is immoral for providing Facebook; they could do it in a better way, but there is no categorical imperative for them to do that.

The problem is this: we, in America, tend to revere people who make a lot of money. When they make a lot of money, we recognize that greed is one of the seven deadly sins, and then we backtrack and we come up with all sorts of other reasons to respect that person. Take, for example, two other icons of the computer world Steve Jobs and Bill Gates. People openly acknowledge that both these characters were ruthless, backstabbing, cunning businessmen, and that’s why they made a lot of money. However, I regularly hear people refer to them as geniuses.

Really? Geniuses? Witness the following identi.ca conversation, where Fabian Scherschel insults Steve Jobs: even from within the free software community, he got replies saying basically “he’s a jerk, not an idiot.” Fab’s response was that insults needn’t be factually correct, which I basically agree with. However, it exposes the problem: we tend to associate “achievement” with “monetary achievement.” I think Jeffrey Lebowski (“the other Lebowski, the millionaire”) exemplifies this attitude best in the world of film characters.

The moral problem is not whether Mark Zuckerberg is a bad person. As I said, it doesn’t matter. What matters is that these are the people that movies are made about. What matters is that when people make a lot of money, we think they are good people, in one way or another.

Don’t write like a spambot

If you’re in the same situation as this guy

I’m currently being held prisoner by the Russian mafia penis enlargement penis enlargement and being forced to post spam comments on blogs and forum! If you don’t approve this they will kill me. penis enlargement penis enlargement They’re coming back now. vimax vimax Please send help! nitip penis enlargement penis enlargement

my advice would be to avoid sprinkling your urgent cry for help with words like “penis enlargement.” I may be old-fashioned, I’ve been using the internet for a long time, but I just think this style of self-expression has a lot of problems. If you really need help, you should definitely not talk about penis enlargement. You can take care of that after I rescue you from the Russian mafia. I did not approve this comment, so I guess I killed this guy — even though I didn’t technically pull the trigger. Sorry pal, but your poor grammar is landing your comment in the trash.

XML: I don’t get it yet

I’m grappling with understanding what XML is really good for. I guess I understand that if I wanted to make an RSS reader or something like that, I would understand it right away. Mostly I’m not trying to understand what it’s good for but how it could help me. I understand that XML is for portable document (broadly-defined) exchange over the web, but it’s the meaning of “document” and “exchange” that require illumination.

I have a few big obstacles. For one, documents describing XML are only about syntax, which for me is the really really really really really really really really really really really really simple part. I mean, how much of a brain does it take to understand well-formedness and hierarchy? What’s hard to understand is poor-formedness and non-hierarchy (i.e. HTML). I reiterate that I come from a Unix background, where it’s impossible to think of things in a non-hierarchical manner, although some bad habits are creeping into the community from outside.

The next big obstacle is that many documents describing XML say that it’s big advantage is storing data in plain text files. My reaction is always “What idiot stores data in an opaque binary that requires a special program to read it?” Again, coming from a Unix background, this idea is hardly revolutionary. So it seems to me that the complexity of XML is a way to bring simplicity out of the Unix world, with just enough annoying complexity to satisfy people who insist on complexity. If it were too simple, they wouldn’t recognize it. So we have a potentially simple thing — data stored in plain text — in a completely verbose form: XML.

That verbosity brings to mind the common complaint about XML, which is that it’s really Lisp syntax with angle brackets and a bunch of stuff inside them. Consequently Lisp is a natural way to deal with XML. Again, this is bringing the ideas of one programming community (the Lisp community) to another (web programming).

I have thought of a few things I could do with XML, but most of all I don’t know why I feel the urge to learn more about it. One would be a graphing program that uses a web server and a browser to view results as SVG. That might be cool. Again, however, I have this voice inside that says “just tie together the right tools and automate them with a Makefile!”

Please share your thoughts.

Net Updates

It’s about time for an update on various cool websites I’ve found. One is DuckDuckGo, a new search engine that really works well. I’ve been using it in deference to Google. DuckDuckGo has a lot of cool features, including nice keyboard controls and a really nice way of presenting results. It also checks for alternate meanings of your search terms and presents them in “disambiguation” format right away. It’s a good mix of the concepts of ask.com and Google. Check it out.

I’ve been searching for a good Web Portal and have been giving Netvibes a good try. It’s really easy to configure and has it’s own Javascript audio player (that really works in Firefox). It also has a Firefox add-on that saves RSS feeds to your home page. Check it out.

Another site I’ve been using for a while now is StackOverflow. This site basically hosts programming questions, but it has a really interesting way of rewarding good answers. I’ve really enjoyed using it. I’d say it’s the best of what Javascript has to offer, i.e. it’s not annoying and doesn’t kill my browser, unlike other websites.

In other news I’m getting back into Scheme programming, more on that later.

New Homepage Look

I’ve fixed up my homepage at UNC using XHTML and new CSS plus some MathML. Tell me what you think!

If you are using Internet Explorer

• Don’t use Internet Explorer
• You may be asked how to download the file

First off you shouldn’t use Internet Explorer at all: it’s old-fashioned, insecure, slow, and can’t read XHTML. You have plenty of alternatives, the best of which is Firefox. Firefox supports XHTML, HTML5, and can play Ogg Theora files. Internet Explorer doens’t do any of that.

Let me know of any other problems, and again tell me what you think of the new look.