Monday, February 11, 2013

Markdown to Word

So here's the use case:
You are increasingly working on your iPad at work. It means you don't have to transcribe hand written notes into some other document and you can write documents completely on your iPad. The problem is that the iPad and Microsoft Word are poor partners. The best way to write on the iPad is to use a Markdown editor. It's a simple markup language, anyone can learn it in 10 minutes and it allows the documents to be re-purposed to Word, HTML, LaTeX, ePub, PDF or whatever. And everybody in the business world wants something in MS Word.
The further problem is that whilst Markdown is the bees knees, it's not trivial to do tables in Markdown. In fact writing tables by hand in Markdown is a pain.
This is a real scenario that's been troubling a couple of people I know. So I've been working on a solution. Here's what the solution and tool chain look like:
  1.  iPad combined with a Bluetooth keyboard. If you are going to write on the iPad then do yourself a favour and get a Bluetooth keyboard so you can touch type.
  2. A Markdown editor. I like Writeup on the iPad but there are heaps of others.
  3. iSSH on the iPad to access the server via ssh.
  4. Dropbox. You have to get stuff on and off  your iPad and there's no better way than Dropbox.
  5. Pandoc on an accessible Mac or Linux or Windows server. More on this below.
  6. R statistical analysis package. Stay in your seat...it will be alright I promise.
  7. These scripts.
Here's the workflow.
  1. You create a Markdown document on your iPad and store it in Dropbox. Where you want a table in the document you put a marker of the form @filename.extension@ into the document on a line of its own.
  2. Create the table data in MS Excel and export it as tab delimited into a separate named file for each table. The filenames must align with your markers from the step above, but without the @ at either end. Any strings with spaces in them in the table need to be quoted: "Jane Smith". Put these files in the same Dropbox folder as the document with the markers in it.
  3. Use iSSH to generate and transfer a key to your server and set up the server to accept that key. That way you can create a session on the server without passwords. Set up iSSH to run a script on login that calls the Main.sh script from step 7 above. This is a one time setup.
  4. Login using iSSH and choose GenerateTables.sh and run through selecting your table data and the output file name once for each table.
  5. Now from Main.sh choose InsertTableMaster.sh and tell it which file has the markers in it and what you want the document called when it has the tables in it. This will replace the markers with the actual tables.
  6. Now from Main.sh choose GenerateWord.sh and it will process your document into a Word document.
If this sounds complex it's not. One of the people using this has never used the Terminal and never wants to but they happily generate Word docs with tables in them. It is very quick. The table insertion process takes seconds to run and the conversion to Word takes under a second to run.
The package of scripts has a detailed Readme.md file with it and you can ask any questions on that site or in comments here. That link takes you to the overview page where you can read the documentation and learn about the very simple pre-requisites. From there you can either do a git clone if you are that way inclined or simply download the files as a zip.

Please give me feedback and suggestions in the comments.

Note 1: Dropbox doesn't update on a computer unless you are logged in. Therefore you need to have a user logged in to the console of the remote computer and that user has to at least have shared the Dropbox folders that you want to use. Otherwise you save a file to Dropbox on the iPad and when you ssh into the server it isn't in Dropbox.
Note 2: Setting up keys for ssh can take a moment but it's worth doing. If you have trouble say so in the comments and I'll write a post on it.

1 comment: