Xnos & shortcaption integration + Dockerization

Dockerfile

@@ -0,0 +1,23 @@
+FROM aergus/latex
+
+RUN apt-get update --assume-yes && \
+apt-get install --assume-yes make \
+python3-dev \
+python3-pip
+RUN tlmgr init-usertree
+RUN tlmgr install truncate \
+tocloft \
+wallpaper \
+morefloats \
+sectsty \
+siunitx \
+threeparttable
+RUN tlmgr update l3packages \
+l3kernel \
+l3experimental
+RUN python3 -m pip install pandoc-fignos pandoc-eqnos pandoc-tablenos \
+pandoc-secnos pandoc-shortcaption
+
+COPY . .
+WORKDIR /data
+ENTRYPOINT ["make"]

Makefile

@@ -6,6 +6,7 @@ INPUTDIR=$(BASEDIR)/source
 OUTPUTDIR=$(BASEDIR)/output
 TEMPLATEDIR=$(INPUTDIR)/templates
 STYLEDIR=$(BASEDIR)/style
+SCRATCHDIR=$(BASEDIR)/scratch
 
 BIBFILE=$(INPUTDIR)/references.bib
 
@@ -16,43 +17,48 @@ help:
 	@echo 'Usage:                                                                 '
 	@echo '   make html                        generate a web version             '
 	@echo '   make pdf                         generate a PDF file  			  '
-	@echo '   make docx	                       generate a Docx file 			  '
-	@echo '   make tex	                       generate a Latex file 			  '
-	@echo '                                                                       '
+	@echo '   make docx	                     generate a Docx file 			      '
+	@echo '   make tex	                     generate a Latex file 			      '
 	@echo ' 																	  '
+	@echo '   multiline_tables                 convert a large markdown table into a$\'
+	@echo '									                                        multi-line format' 
 	@echo ' 																	  '
+	@echo '   tables	                       convert a md table into LaTeX, to$\'
+	@echo '                                       be used sideways or with other$\'
+	@echo '      			                       advanced formatting'															
+	@echo '                                                                       '
 	@echo 'get local templates with: pandoc -D latex/html/etc	  				  '
 	@echo 'or generic ones from: https://github.com/jgm/pandoc-templates		  '
 
 pdf:
-	pandoc "$(INPUTDIR)"/*.md \
+	pandoc  \
+	--filter=pandoc-shortcaption \
+	--filter=pandoc-xnos \
+	"$(INPUTDIR)"/*.md \
 	-o "$(OUTPUTDIR)/thesis.pdf" \
 	-H "$(STYLEDIR)/preamble.tex" \
-	--template="$(STYLEDIR)/template.tex" \
 	--bibliography="$(BIBFILE)" 2>pandoc.log \
 	--csl="$(STYLEDIR)/ref_format.csl" \
-	--highlight-style pygments \
 	-V fontsize=12pt \
 	-V papersize=a4paper \
 	-V documentclass=report \
-	-N \
 	--pdf-engine=xelatex \
 	--verbose
 
 tex:
 	pandoc "$(INPUTDIR)"/*.md \
-	-o "$(OUTPUTDIR)/thesis.tex" \
-	-H "$(STYLEDIR)/preamble.tex" \
 	--bibliography="$(BIBFILE)" \
 	-V fontsize=12pt \
 	-V papersize=a4paper \
 	-V documentclass=report \
 	-N \
 	--csl="$(STYLEDIR)/ref_format.csl" \
-	--latex-engine=xelatex
 
 docx:
-	pandoc "$(INPUTDIR)"/*.md \
+	pandoc \
+	--filter=pandoc-shortcaption \
+	--filter=pandoc-xnos \
+	"$(INPUTDIR)"/*.md \
 	-o "$(OUTPUTDIR)/thesis.docx" \
 	--bibliography="$(BIBFILE)" \
 	--csl="$(STYLEDIR)/ref_format.csl" \
@@ -61,6 +67,8 @@ docx:
 html:
 	pandoc "$(INPUTDIR)"/*.md \
 	-o "$(OUTPUTDIR)/thesis.html" \
+	--filter=pandoc-shortcaption \
+	--filter=pandoc-xnos \
 	--standalone \
 	--template="$(STYLEDIR)/template.html" \
 	--bibliography="$(BIBFILE)" \
@@ -72,4 +80,13 @@ html:
 	mkdir "$(OUTPUTDIR)/source"
 	cp -r "$(INPUTDIR)/figures" "$(OUTPUTDIR)/source/figures"
 
-.PHONY: help pdf docx html tex
+multiline_tables:
+	pandoc "$(SCRATCHDIR)/tables.md" \
+	-t markdown+multiline_tables \
+	-o "$(SCRATCHDIR)/cleaned_tables.md"
+
+tables: multiline_tables
+	pandoc "$(SCRATCHDIR)/cleaned_tables.md" \
+	-o "$(SCRATCHDIR)/tables.tex"
+
+.PHONY: help pdf docx html tex multiline_tables tables

README.md

@@ -19,6 +19,7 @@ Markdown is a super-friendly plain text format that can be easily converted to a
 - it automatically handles the table of contents, bibliography etc with Pandoc.
 - comments, drafts of text, etc can be added to the document by wrapping them in <!--  -->
 - it works well with Git, so keeping backups is straightforward. Just commit the changes and then push them to your repository.
+- it is able to take advantage of autocompletion capabilities for figures and citations in several text editors (VSCode, Sublime, etc.)
 - there is no lock-in. If you decide that Markdown isn't for you, then just output to Word, or whatever, and continue working in the new format.
 
 ## Are there any reasons not to use Markdown?
@@ -37,35 +38,46 @@ There are some minor annoyances:
 - Makefile => contains instructions for using Pandoc to produce the final thesis.
 - output/ => directory to hold the final version.
 - source/ => directory to hold the thesis content. Includes the references.bib file.
+- scratch/ => directory to hold tables which can be converted between different formats.
 - source/figures/ => directory to hold the figures.
 - style/ => directory to hold the style documents.
 
 ## How do I get started?
 
-1. Install the following software:
-    - A text editor, like [Sublime](https://www.sublimetext.com/), which is what you'll use write the thesis.  
-    - A LaTeX distribution (for example, [MacTeX](https://tug.org/mactex/) for Mac users).
-    - [Pandoc](http://johnmacfarlane.net/pandoc), for converting the Markdown to the output format of your choice.  You may also need to install [Pandoc cite-proc](http://pandoc.org/demo/example19/Extension-citations.html) to create the bibliography.
-    - Install @martisak's shortcaption module for Pandoc, with `pip install pandoc-shortcaption`
-    - Git, for version control.
-2. [Fork the repository](https://github.com/tompollard/phd_thesis_markdown/fork) on Github  
-3. Clone the repository onto your local computer (or [download the Zip file](https://github.com/tompollard/phd_thesis_markdown/archive/master.zip)).  
-4. Navigate to the directory that contains the Makefile and type "make pdf" (or "make html") at the command line to update the PDF (or HTML) in the output directory.  
-**In case of an error** (e.g. `make: *** [pdf] Error 43`) run the following commands:  
-    ```
-    sudo tlmgr install truncate
-    sudo tlmgr install tocloft
-    sudo tlmgr install wallpaper
-    sudo tlmgr install morefloats
-    sudo tlmgr install sectsty
-    sudo tlmgr install siunitx
-    sudo tlmgr install threeparttable
-    sudo tlmgr update l3packages
-    sudo tlmgr update l3kernel
-    sudo tlmgr update l3experimental
-    ```
-
-5. Edit the files in the 'source' directory, then goto step 4.  
+For both of these methods, you'll need 
+
+- A text editor like [Sublime](https://www.sublimetext.com/) or [VSCode](https://code.visualstudio.com)
+- Git for version control
+
+After installing git:
+1. [Fork the repository](https://github.com/tompollard/phd_thesis_markdown/fork) on Github  
+2. Clone the repository onto your local computer (or [download the Zip file](https://github.com/tompollard/phd_thesis_markdown/archive/master.zip))
+
+### The easy way: Docker
+
+1. Install [Docker](https://www.docker.com/get-started)
+2. Navigate into your newly cloned repository, and type
+
+    ```docker build -t denrondal/md_thesis .``` 
+
+    into the terminal. This will take several minutes.
+
+3. Now you can convert the sample dissertation to pdf:
+
+    ```docker run --volume "`pwd`:/data" dendrondal/md_thesis pdf```
+
+That's it! You should see a sample pdf in the output directory. Note that `pdf` can be subsituted with any other command. To see all commands, just run ```docker run --volume "`pwd`:/data" dendrondal/md_thesis help```
+
+### The hard way: Install everything locally
+
+1. Install the following software:  
+    - A LaTeX distribution (for example, [MacTeX](https://tug.org/mactex/) for Mac users, or [TexLive](https://tug.org/texlive/) for Linux/Windows users).
+    - [Pandoc](http://johnmacfarlane.net/pandoc), for converting the Markdown to the output format of your choice.  
+    - [Python 3](https://www.python.org/downloads/) and python3-pip
+    - Pandoc plugins by running ```bash install.sh``` in the main directory. **If you are on windows, you will need to install the pandoc plugins in this file manually**. This may work on WSL, but has not been tested.
+2. Navigate to the directory that contains the Makefile and type "make pdf" (or "make html") at the command line to update the PDF (or HTML) in the output directory.
+
+**In case of an error** (e.g. `make: *** [pdf] Error 43`), consult [this article](https://dalwilliams.info/lessons-learned-from-writing-a-phd-dissertation-in-markdown.html) for possible fixes. Most importantly, make sure tlmgr is properly installed, then run ```install.sh``
 
 ## What else do I need to know?
 

install.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+sudo apt-get install pandoc-citeproc &&
+sudo tlmgr install truncate &&
+sudo tlmgr install tocloft &&
+sudo tlmgr install wallpaper &&
+sudo tlmgr install morefloats &&
+sudo tlmgr install sectsty &&
+sudo tlmgr install siunitx &&
+sudo tlmgr install threeparttable &&
+sudo tlmgr update l3packages &&
+sudo tlmgr update l3kernel &&
+sudo tlmgr update l3experimental &&
+pip3 install pandoc-fignos pandoc-eqnos pandoc-tablenos \
+            pandoc-secnos pandoc-shortcaption