New features I would love to see in writeLaTeX

Laboratory notes template on writeLaTeX.com

Laboratory notes template on writeLaTeX.com

UPDATE: Since I wrote this post writeLaTeX has added Rich Commenting and BibTeX imports from cloud services.

writeLaTeX is my new favourite thing. If you haven’t heard of it, writeLaTeX is an online service for writing collaborative LaTeX documents. Think of it like Google docs for scientists and people who like to typeset very beautiful documents.

Why does this matter? Well, it solves a whole bunch of simple problems for me. I can move between different machines at home and work and keep the same environment. This is more difficult than just auto-syncing my own documents via Dropbox or similar. It also means I need the same LaTeX environment, whether I am working on a locked-down Windows machine at work or a completely open laptop running FOSS software at home. Already that’s something that removes many of my document writing headaches.

More than providing just a synchronisation service, I can collaborate with colleagues in real-time, so I never need to worry about using the “latest” version of any document — even if my colleagues don’t use versioning software like Git or Mercurial. Beyond that, writeLaTeX automatically compiles my projects in the background, so I can always see a nearly up to date version of the resulting PDF. My favourite way of editing on writeLaTeX is to have a full “editor” window in my main monitor (straight ahead of me) and a full “pdf render” window on another monitor (off to the side). It’s super-convenient and allows me to concentrate without feeling interrupted by compiler warnings or errors when I’m half way through a complicated edit.

I could go on and on, but you get the point – writeLaTeX is a very, very neat way to typeset beautiful documents.

Of course, writeLaTeX is not the only start-up in this space. Authorea and ShareLaTeX make similar offerings, and both have different and interesting strengths. It happens that when I needed a service like this, writeLaTeX was the app that had all the built-in style and class files I needed, and the right combination of features, for me. In fact, the pre-installed TeX packages are exactly what you get from installing all of TeXLive on Ubuntu — so writeLaTeX essentially mirrors my own Linux set-up, minus my dodgy Makefiles. That said, I’m very excited that a few competitors are working on these problems. This tells me that online, collaborative LaTeX services have a serious long-term future, and that should benefit users of all these different services.

Once you start using a new shiny toy, there’s always the sense that this is *so* awesome, I wish it could do X… So this is my current wish list for writeLaTeX. This is no criticism of the awesome service, but if you happen to have a few million dollars lying around, please pay the company to implement the below…

Auto-sync with GitHub, BitBucket and similar

It’s really convenient to have all my writeLaTeX projects together on a writeLaTeX project page, but it also breaks the structure of  my projects and documents and imposes a second, different structure.

This is what I call the expression problem of scientific projects (Computer Scientists will get the joke) – you can either organise your documents and code around each project you take part in (Option 1), or you can organise your documents around their type (Option 2). Either choice is good, and just a matter of personal taste, but it makes a big difference to your personal workflow and how quickly you can find information and track the progress of your projects. Like many things, consistency is the key principle here.

Option 1 looks like this:

science_project1/
....papers/
........paper1/
............main.tex
............figures/
................chart1.png
................petri_dish.png
............refs.bib
........paper2/ ...
....talks/
........talk1/
............main.tex
............figures/
................chart1.png
................petri_dish.png
............refs.bib
........talk2/ ...
....software/
........some_code.py ...
...
science_project2/ ...

Option 2 looks like this:

papers/
....paper_about_project1/
........main.tex
........figures/
............chart1.png
............petri_dish.png
........refs.bib
....paper_about_project_2/ ...
talks/
....talk_about_project1/
........main.tex
........figures/
............chart1.png
............petri_dish.png
........refs.bib
....talk_about_project2/ ...
software_about_project1/
....some_code.py ...
...

But what happens when you start to use services like writeLaTeX? Your whole workflow gets a lot more complex. You might have all of your projects sync’s to a service like GitHub, or not, but now your papers and talks are on writeLaTeX and can’t be “checked out”. Your software might well be on GitHub or similar. You might well be sending your figures and data off to FigShare. It is suddenly more difficult to keep everything together and it isn’t immediately clear how much progress you have made with each part of the project.

In my view the answer to this problem has to come in two parts. Firstly a way to expose writeLaTeX projects as git repositories so that they can be incorporated as git submodules inside an existing GitHub project (other SCMs and hosting companies are available). This means that it doesn’t matter whether you choose Option 1 or Option 2 above to structure your project files. writeLaTeX could then issue pull requests on GitHub when you update your documents to “send” your updates to GitHub. Secondly, existing CI services such as Travis can be configured to send documents off to FigShare once a tagged release of a paper has been created. This costs a little time to set up, but it is an automated workflow that can be reused over different projects, so that small set-up cost is nicely amortized.

Linting

lint is a tool to check code for errors before it has been compiled. There are a number of these for LaTeX (the one I currently use is chkTeX), and it would be useful to have them run automatically during the background built-compile-render cycle that writeLaTeX already runs.

If you are not writeLaTeX one option here is to use a continuous integration tool to run the lint for you, together with your normal build cycle. For example, this:

is a Travis recipe for running chkTeX over a project, and this is the result of the current Travis build of my UoW PhD template:

$ chktex -W
ChkTeX v1.6.4 - Copyright 1995-96 Jens T. Berger Thielemann.
The command "chktex -W" exited with 0.
$ chktex -q -n 6 *.tex chapters.*.tex 2>/dev/null | tee lint.out
The command "tee lint.out" exited with 0.
$ test ! -s lint.out
The command "test ! -s lint.out" exited with 0.

A way to copy and share files between different projects

There are a few jobs that need to be done for any paper, but are time-consuming busy work that ideally would be minimised. One of these is producing and curating long lists of references to prior art, usually in BibTeX. Another is pulling in tables and figures (usually to do with prior art or experimental apparatus) that can be used in different papers. An obvious example is a BibTeX file containing the authors own papers. You might have a file called something like mypapers.bib which you certainly need in your own CV, but then you also need in pretty much all your papers and several talks. What happens when you update this file for your CV project? mypapers.bib isn’t shared between different projects, so if you also need to update it in all your other projects. That might not be so bad when you are just added a newly published paper to your list, but if you find a typo in your old papers it’s a real pain. The same is true for curated lists of papers in the area you work in and all sorts of other files.

It would be nice to find some clever way to resolve this, but what if you also have all your files nicely structured and curated using either Option 1 or Option 2 above? Maybe a neat thing to do would be to have some “dummy” projects which only contain common files, such as BibTeX files (and don’t get compiled with pdflatex or similar), then use something like Git submodules to “import” the dummy projects into “real” ones that do compile documents. 

More help with BibTeX

If there’s one huge and pointless sink of valuable time it’s curating long lists of BibTeX references. In recent years a number of services have started to make this easier — Bibsonomy and Google Scholar being two very handy services — but there is still much that has to be done manually. A neat way to search for a citation and pull it into a BibTeX file from within writeLaTeX would be really, really cool.

Some crazy form of document review

Open document review has started to become common, at least for books. A great example of this is Real World OCaml where you can log in with a GitHub account and comment on any paragraph of the book. Comments then become issue tickets in a GitHub repository and the authors can resolve each comment (I notice Real World OCaml has logged an impressive 2457 closed tickets). This is a really neat solution to document review and would be a huge bonus for anyone writing in LaTeX.

Advertisements
This entry was posted in Research and tagged , , , , , , , , . Bookmark the permalink.

Please leave a response

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s