Archive

Posts Tagged ‘publishing’

Set up a website using Emacs’ Org Mode

January 17, 2012 3 comments

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.

Advertisements
Categories: Emacs, Web Tags: , , , ,

A Second Look at Open Access

November 23, 2010 3 comments

Today I took a look at some more articles and some more videos on the web introducing myself to the concepts of Open Access. I also talked to a professor at my university who pointed me to some interesting links. The impact factor of Open Access journals is rapidly approaching that of non-OA journals. That is interesting: I definitely want to support Open Access, but as I said yesterday, I simply find some of the arguments lacking.

I was browsing through some videos on Youtube and just as I was thinking “Why are these all from people I’ve never heard of?” I found one from someone I have heard of (and, incidentally, whose papers I read quite a lot of): Andrew Pomiankowski.

Pomiankowski points out several advantages of BMC Journals:

  1. Fast peer review
  2. Fast turnaround from submission to publication
  3. Creating competition for journal publishers, who have been “ripping off” scientists for a while now

Okay, now he’s speaking my language. I definitely think the publishers need competition. And if they genuinely have been ripping off scientists (and I have no reason to think he’s lying, having seen the whole process from submission to publication), then that’s something we need to rebel against.

Another critical argument that didn’t come up right away in my investigations was authors retaining copyright. Open Access journals don’t demand copyright assignment from the authors of scientific works. Instead authors retain the rights to distribute their own works in their own ways. The articles are still peer-reviewed and still perfectly reputable, but you can get them from a colleague’s website while reading his CV, instead of following links that might not work. That is compelling.

What’s holding me back? What’s holding me back from saying “I will only publish in open access journals?” The fact that a journal like Evolution, or American Naturalist is not Open Access still doesn’t deter me. Those are good journals. I would be more than proud to publish a paper in any one of many good “closed access” journals. As I said yesterday, I also still can’t discount the value of a good paper because it’s not in an Open Access journal.

However, things are changing. Within ten or twenty years I doubt there will be many “closed access” journals. The journals I just mentioned are already putting open data policies into effect. Open data to open access takes very few steps, although it may involve pissing off, losing, or forcing the hand of the publisher. If Wiley-Blackwell can’t provide the kind of access that scientists want, then they may just go out of business. I think a lot of scientists do want that level of access, so I think Wiley-Blackwell, Elsevier, Springer and company will have to change. Either that or they’ll just keep merging until there will be only one such publisher to put out of business.

I do think the access the web allows people is an unstoppable force. The trick is to take the best part of the freedom of the internet (access) and not let the content fall victim to the worst part of the worst part of the freedom of the internet: barriers to entry for authors. Any jerk can say whatever the hell he wants and you’ll still probably read it. You for example, reading the blog of a graduate student when you should be reading something over at PLoS. We need to make sure that all the good things about journals and the peer-review process stay in place, while making the journals as easily accessible as this blog.

Just for fun, here’s another biologist that I have heard of, Steve Jones:

Considering the benefits of Open Access

November 22, 2010 7 comments

Open Access is an aspect of free culture that I have not fully evaluated yet. I want to be able to take a position on the subject, should the question come up, so this week I’m making a concerted effort to understand what Open Access (capitalized) is, what its major tenets and who its major supporters are. I don’t want to take a knee-jerk reaction to it and say “I think free software is ethical, therefore open access is ethical.” That’s a little short-sighted. Furthermore, although I agree with certain arguments from open access immediately (scientists should make their data and source code available), I certainly don’t want to ally myself with a movement that I don’t understand. People could end up thinking I want to take away their jobs, and that might not be true.

I just watched a short video on the subject:

Open Access is just one of those things that should be a given as far as scientific research is concerned.

Not so fast. Yes, scientists should make their data available to all readers of their work. Any qualified scientist should be able to take that data and come to similar conclusions; this is what peer review is all about. However, that doesn’t necessarily mean that people shouldn’t pay for access to journals. For one thing most people who access scientific journals pay for them indirectly by paying student fees that go toward university library subscriptions. Another thing is that most people aren’t scientists: they don’t know how to evaluate scientific literature and they can frequently take things out of context. Especially where we consider the news media, there should be some barriers to entry. There are many places where intellectual elitism is a good thing and having a moderate barrier to entry for those things is a good idea.

Furthermore, when you publish a scientific paper, even in a “closed” journal, you’re doing the antithesis of “hiding it away.” Publication in any form is opening up your research to the public. The only way to hide something away is to not publish it, and then no one knows about it. You don’t have to publish in an Open Access journal to be making your research public.

Finally as to the above remark: most people at universities have access to journals online, whether those journals are Open Access or not. It’s not a question of whether you can see it or not.

At 1:58 we hear this

The way I use the literature has changed completely…go to Pubmed, search and then click on the links…I’m more likely to read that work

Whether you have access to an article’s text or not usually does not depend on whether the journal is Open Access. There is no difference between accessing Evolution versus accessing PLoS One, as far as access to text goes, if you’re at a university with a subscription to Evolution. I would find it hard to believe that King’s College London doesn’t have a subscription to the world’s leading journal in evolutionary biology.

At 2:07 we hear something even more provocative:

People who do publish in open access journals will find their work being more used more accessible by a growing group of people, whereas people who continue to publish in closed journals will, I’m afraid to say, have their work dismissed or ignored over time.

I’ve got two words for that opinion: BULL SHIT. As of now I would never “dismiss or ignore” a work simply because it’s published in the best-edited, best-printed, and best-run journal simply because it’s not Open Access. That is simply crazy. Perhaps in the future there will be holdouts who refuse to grant open access to data, but I would not completely discount such a journal; beside that, most journals are heading to open data regardless of whether they still want people to pay for a subscription. That quotation may be taken out of context by the editors of the film, but I just find it outrageous to consider that I would read a perfectly good paper and say “Well, this isn’t in PLoS, so it’s crap; I’m going to ignore it.” That would not serve me as a scientist at all.

After doing a little research and hearing a few opinions, I will not advocate Open Access for right now, the way I advocate free software. I will tell people “Free Software is better for personal and academic liberty, and creates a society with better values.” I can’t say the same things in support of Open Access. However, I will take it seriously and continue to consider its benefits. I’m certainly not going to advocate it as the One True Way, like Dr. Birney.

%d bloggers like this: