Writing an academic paper in plain text and sharing everywhere: part IV of the series

Part I here
Part II here
Part III here

Preamble

In the previous three parts of this series, I have discussed three different tools that let you craft an academic or scholarly argument and push or publish it into different “outlets”. The purpose of this series is to explore all plain text based tools or tools that depend on minimal rich text formatting to write scholarly documents and publish everywhere. In this series, I mean by scholarly document as a document you write which has the following characteristics:

1. The document is essentially non-fiction but it could be a fictionalised document as well
2. The document may contain (not necessarily so) tables, figures, lists, codes, equations. Not all elements will be found in any one document, but it should be possible to write them and you, as a writer, should be able to see them in the final version, whatever format it takes
3. The document will definitely need to contain evidence based information, in other words, when you write the document and state a fact in it, you should be able to provide an attribution in the form of a citation and a tagged reference, and also optionally, hyperlinks that will link the document to another document over the world wide web or another source
4. It should allow for collaborative editing or sharing an editable version of the paper

In general, the de facto format that people write their documents are varied, but in most scholarly journals, the documents are presented in the form of PDF documents or ePubs. ePubs are increasingly becoming popular, and more and more services are now available to extract meta data from PDFs and present them in reference management systems which in turn play well with most word processors. Further, a popular way to write text in free text or plain text format is LaTeX but LaTeX can be quite complex in terms of the various tags and the compilation process it has to go through. Not the least daunting thing about LaTeX writing is formatting of tables, except for the most simple tabular format, LaTeX is not the most user friendly. There have been a number of very interesting programmes and software that have attempted to take out the tedium of writing in LaTeX and even emulated a nice WYSIWYG interface for writing in LaTeX. A very tidy example is using LyX to write in LaTeX but using a WYSIWYG interface. Nevertheless, writing in LaTeX remains complex and many scholars in humanity and life sciences for example (those who are not in Math Stats Epidemiology Computer science, Engineering and related fields) tend to avoid if they can the tedium of writing in LaTeX.

A number of web based adaptations of LaTeX are now available. Of these a few stand out. Authorea is an example where the developers attempted to merge and meld HTML format and LaTeX to enable people write documents. This is also one where you can write and publish to various formats and push your articles to a limited range of journals for instance. Another example is ShareLaTeX which provides a web based LaTeX writing interface. A very nice and functional example is Overleaf that allows you to write in a nice web based WYSWYG format and also provides dozens of templates and several journals and formats where you can push your publication. Indeed, services such as these have lowered the barriers of publishing and writing in plain text highly complex technical documents and then push it to several places.

Added to this lowered barriers, the learning curve has further been flattened by Markdown format. A number of great web based and offline apps are now available and you can write anywhere and publish anywhere including blogs. Thus, I argued that a combination of writing in Markdown and then pushing and processing in Overleaf will unleash the power of writing in a simple elegant format, then pushing the plain text through a parser that will convert the text to LaTeX format and then uploading the document further to Overleaf will address all the four issues I mentioned above. Based on this conceptualisation, I argued that a three step process will work well:

1. Write the substance in a Markdown style app or a plain text app
2. Transform the document to LaTeX using Pandoc, a Haskell script written by John MacFarlane. In order to do that, do Cmd+Shift+P in Mac, or Control+Shift+P in Linux/Windows
3. You can also alternatively or additionally convert the Markdown to HTML (it natively allows for this). Then, on the one hand, you can push your article (one version of it to a scholarly journal for publishing), and you can push another version for a more laid back, easier to read HTML or to your blog for seeking further input. You can also, in this way, use your blog as an outlet of your scholarly publishing medium.
4. Upload the document to something like Overleaf, and let it be pushed to Scholarly journals for publishing through Overleaf, but also share and seek comments from a wider audience through your “circles”.

Enter Sublime Text

In the first article of this series, I wrote about Ulysses, a popular content authoring app and wrote how this can be used to write in Markdown and then with Pandoc, it can be used to create nice LaTeX formatted document. I also wrote that Ulysses makes it easy to publish to blogs and Medium in one click, so that parts of the document can be pushed to Medium to seek ideas and build discussions. In the second article of the series, I examined another app, Classeur.io, another Markdown writing app that would not require you to install Pandoc but it has built-in features to export the material to LaTeX and html and you can use it to directly push your writing to your blog or a static html page. In the third article of the series, I wrote about using Manuscripts.app, an app that would let you convert everything directly to LaTeX and let you write. Manuscripts is still rough at edges in the sense that you cannot create nicely formatted HTML document (as links do not show), but otherwise very promising.

In this part, I am going to examine using popular coding tools to do the writing in markdown and then export in LaTeX and HTML so that an article or an idea can be flexibly sent for further processing:

1. Write in the app
2. Process in Overleaf or in the app
3. Share through Overleaf

The idea is to be minimalistic and be as less complex as possible. Sublime Text provides such an idea development opportunity. Sublime Text is free to download and use but you can buy a personal licence to use it. Thus it is a free text and code editor. There is already a considerable amount of information available about configuring Sublime Text as a full fletched academic writing environment. If you are interested to learn more about using Sublime Text as an academic writing environment, definitely check Christopher Grainger’s blog

Configuring Sublime Text as a markdown-latex-html medium workflow is very simple. Sublime Text editor is extensible by using packages that you can install. To get started, do:

1. Download and install Sublime Text Editor
2. Then, in Mac do Cmd-Shift-P
3. In the search box, type Install or beging to type “Install”
4. It will show install packages and click on that
5. It will show a list of packages that you can install. Definitely install the following at the least for a nice working environment with Pandoc and Markdown.

These three or four packages are:

1. Markdown Editing
2. Markdown Preview
3. Pandoc
4. Citer (there are other alternatives to Citer, but I have used Citer so far and I am happy about it)

To get markdown preview work seamlessly with a web browser, install the package Live Reload in Sublime Text. For more instructions, follow the instructions here:

How to install live reload package for Sublime Text

This will enable you to convert your markdown file directly to an html file and you can also use this to post to your blogs. You will also need to configure your Pandoc installation for Sublime Text. Before you can use the Pandoc package, you need to install Pandoc on your computer where you will be working, and after installing Pandoc, you will need to provide Sublime Text with instructions as to where to find Pandoc and configuration files. To do so, do (this is for Mac, you will find corresponding instructions for Windows and others):

1. Go to Sublime Text >> Preferences >> Package Settings >> Pandoc >> Settings-User and click there
2. Use the pandoc.sublime-settings file to set the settings for your specific working environment, provide the information where to find the pandoc-citeproc file on your system, where to find pandoc executable on your system, and provide a default bibliograhy file and a style file system, and you are all set to go. You can google pandoc.sublime-settings and learn from several users who have provided their pandoc sublime settings on public domain.

Processing with Overleaf and Sharing

This will provide you with a decent workflow to work with Sublime Text and LaTeX. You can transform your Sublime Text markdown paper to LaTex and upload the LaTeX document to Overleaf. Using Overleaf, you can distribute the paper to other repositories, submit the papper to journals, style the document to submit to other journals, or submit to PeerJ, or elsewhere. Check out Overleaf for more details.

Do Medium and blogs play well?

You can upload a resulting fully formatted markdown file converted to html for publishing to your blog or to a static page. You can also copy and paste most of it and paste to Medium. However, for Medium, to show tables, they have to be in image format. Most other features tend to work well as in the fully formatted html document.

Next Steps

Continuing our journey with this tour of the different text editors that will enable us to write in Markdown and then share and submit using LaTeX and Overleaf, our next stop tomorrow for our part V will be how to use Atom and configure Atom code editor to write scholarly articles and share everywhere.