Dockerization & Multiline tables

.travis.yml

@@ -11,6 +11,8 @@ language: bash
 
 os: osx
 
+services: docker
+
 env:
   global:
     - PATH=$TRAVIS_BUILD_DIR/usr/bin/:$PATH
@@ -28,6 +30,7 @@ before_install:
   # - sudo apt-get install texlive-science
   # # Install fonts
   # - sudo apt-get install lmodern
+  - docker build -t dendrondal/md_thesis .
   - brew install pandoc
   - brew install pandoc-citeproc
   - brew cask install mactex
@@ -40,3 +43,4 @@ script:
   - make pdf
   - cat pandoc.log
   - make html
+  - docker run --volume "`pwd`:/data" dendrondal/md_thesis pdf

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

@@ -11,23 +11,29 @@ SCRATCHDIR=$(BASEDIR)/scratch
 BIBFILE=$(INPUTDIR)/references.bib
 
 help:
-	@echo ' 																	  '
+	@echo ' 							'
 	@echo 'Makefile for the Markdown thesis                                       '
 	@echo '                                                                       '
 	@echo 'Usage:                                                                 '
-	@echo '   make install                     install pandoc plugins
-	@echo '   make html                        generate a web version             
+	@echo '   make install                     install pandoc plugins             '
+	@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 '   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		  '
 
 install:
 	sh $(BASEDIR)/install.sh
-	
+
 pdf:
 	pandoc  \
 	--filter=pandoc-shortcaption \
@@ -82,5 +88,13 @@ html:
 	mkdir "$(OUTPUTDIR)/source"
 	cp -r "$(INPUTDIR)/figures" "$(OUTPUTDIR)/source/figures"
 
+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 install pdf docx html tex 
+.PHONY: help install pdf docx html tex

README.md

@@ -1,4 +1,4 @@
-# Template for writing a PhD thesis in Markdown [![Build Status](https://travis-ci.org/tompollard/phd_thesis_markdown.svg?branch=master)](https://travis-ci.org/tompollard/phd_thesis_markdown)  
+# Template for writing a PhD thesis in Markdown [![Build Status](https://travis-ci.org/tompollard/phd_thesis_markdown.svg?branch=master)](https://travis-ci.org/tompollard/phd_thesis_markdown)
 
 [![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.58490.svg)](http://dx.doi.org/10.5281/zenodo.58490)
 
@@ -27,7 +27,7 @@ Markdown is a super-friendly plain text format that can be easily converted to a
 There are some minor annoyances:
 - if you haven't worked with Markdown before then you'll find yourself referring to the style-guide fairly often at first.
 - it isn't possible to add a short caption to tables ~~and figures~~ ([figures are now fixed](https://github.com/tompollard/phd_thesis_markdown/pull/47), thanks to @martisak). This means that /listoftables includes the long-caption, which probably isn't what you want. If you want to include the list of tables, then you'll need to write it manually.
-- the style documents in this framework could be improved. The PDF and HTML (thanks [@ArcoMul](https://github.com/ArcoMul)) outputs are acceptable, but ~~HTML and~~ Word needs work if you plan to output to this format.  
+- the style documents in this framework could be improved. The PDF and HTML (thanks [@ArcoMul](https://github.com/ArcoMul)) outputs are acceptable, but ~~HTML and~~ Word needs work if you plan to output to this format.
 - ~~there is no straightforward way of specifying image size in the markdown right now, though this functionality is coming (see: https://github.com/tompollard/phd_thesis_markdown/issues/15)~~ (Image size can now be specified. Thanks to @rudolfbyker for [highlighting this](https://github.com/tompollard/phd_thesis_markdown/issues/15)).
 - ... if there are more, please add them here.
 
@@ -44,18 +44,40 @@ There are some minor annoyances:
 
 ## How do I get started?
 
+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 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.  
-    - Pandoc plugins by running ```make install```
-    - 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.  
+    - 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 ```make install``` 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``
-
-5. Edit the files in the 'source' directory, then goto step 4.  
 
 ## What else do I need to know?
 
@@ -68,6 +90,17 @@ Some useful points, in a random order:
 - For fellow web developers, there is a Grunt task file (Gruntfile.js) which can be used to 'watch' the markdown files. By running `$ npm install` and then `$ npm run watch` the PDF and HTML export is done automatically when saving a Markdown file.
 - You can automatically reload the HTML page on your browser using LiveReload with the command `$ npm run livereload`. The HTML page will automatically reload when saving a Markdown file after the export is done.
 
+### Problems with tables
+
+Sometimes, either multiple lines of text are needed in a table cell, Pandoc will incorrectly render tables with text overlapping, or the whitespace in your columns doesn't make sense. There are `make` directives to fix this, which work as follows:
+
+1. Create a markdown file outside of the source directory (/scratch/tables.md in this repository)
+2. Paste your problem tables (in markdown form) into this file
+3. Run `make multiline_tables`
+4. Paste the new multi-line tables where the original tables would be in your document
+
+If you need a table in landscape mode, or need to apply advanced LaTeX formatting, the `make_tables` directive will do this for you. Again, consult [this blog post](https://dalwilliams.info/lessons-learned-from-writing-a-phd-dissertation-in-markdown.html) for troubleshooting.
+
 # Contributing
 
 Contributions to the template are encouraged! There are lots of things that could be improved, like:

scratch/cleaned_tables.md

@@ -0,0 +1,25 @@
+  -----------------------------------------------------------------------------------
+    Landmass     \%    Number of  Dolphins per    How Many     How Many    Forbidden
+                stuff    Owls        Capita         Foos         Bars        Float
+  ------------ ------- --------- -------------- ------------ ------------ -----------
+     North       94%    20,028       17,465        12,084       20,659       1.71
+    America                                                               
+
+    Central      91%     6564         6350         8,189        12,012       1.52
+    America                                                               
+
+     South       86%     3902         4127         5,205        6,565        1.28
+    America                                                               
+
+     Africa      84%     2892         3175         3,862        4,248         1.1
+
+     Europe      92%    20,964       17,465        15,303       24,203       1.58
+
+      Asia       87%     6852         6350         8,255        11,688       1.47
+
+    Oceania      87%     4044         4127         5,540        6,972        1.28
+
+   Antarctica    83%     2964         3175         4,402        4,941        1.13
+  -----------------------------------------------------------------------------------
+
+  Table: Important data for various land masses. {#tbl:random}

scratch/tables.md

@@ -0,0 +1,12 @@
+| Landmass       | \% stuff | Number of Owls | Dolphins per Capita | How Many Foos | How Many Bars | Forbidden Float  |
+|:--------------:|:--------:|:-------------:|:--------------------:|:-----------------:|:-----------------:|:------:|
+| North America  | 94%    | 20,028      | 17,465             | 12,084          | 20,659          | 1.71 |
+| Central America  | 91%    | 6564        | 6350               | 8,189           | 12,012          | 1.52 |
+| South America  | 86%    | 3902        | 4127               | 5,205           | 6,565           | 1.28 |
+| Africa  | 84%    | 2892        | 3175               | 3,862           | 4,248           | 1.1  |
+| Europe | 92%    | 20,964      | 17,465             | 15,303          | 24,203          | 1.58 |
+| Asia | 87%    | 6852        | 6350               | 8,255           | 11,688          | 1.47 |
+| Oceania | 87%    | 4044        | 4127               | 5,540           | 6,972           | 1.28 |
+| Antarctica | 83%    | 2964        | 3175               | 4,402           | 4,941           | 1.13 |
+
+Table: Important data for various land masses. {#tbl:random}

scratch/tables.tex

@@ -0,0 +1,161 @@
+\begin{longtable}[]{@{}ccccccc@{}}
+\caption{Important data for various land masses.
+\{\#tbl:random\}}\tabularnewline
+\toprule
+\begin{minipage}[b]{0.12\columnwidth}\centering
+Landmass\strut
+\end{minipage} & \begin{minipage}[b]{0.07\columnwidth}\centering
+\% stuff\strut
+\end{minipage} & \begin{minipage}[b]{0.09\columnwidth}\centering
+Number of Owls\strut
+\end{minipage} & \begin{minipage}[b]{0.14\columnwidth}\centering
+Dolphins per Capita\strut
+\end{minipage} & \begin{minipage}[b]{0.12\columnwidth}\centering
+How Many Foos\strut
+\end{minipage} & \begin{minipage}[b]{0.12\columnwidth}\centering
+How Many Bars\strut
+\end{minipage} & \begin{minipage}[b]{0.12\columnwidth}\centering
+Forbidden Float\strut
+\end{minipage}\tabularnewline
+\midrule
+\endfirsthead
+\toprule
+\begin{minipage}[b]{0.12\columnwidth}\centering
+Landmass\strut
+\end{minipage} & \begin{minipage}[b]{0.07\columnwidth}\centering
+\% stuff\strut
+\end{minipage} & \begin{minipage}[b]{0.09\columnwidth}\centering
+Number of Owls\strut
+\end{minipage} & \begin{minipage}[b]{0.14\columnwidth}\centering
+Dolphins per Capita\strut
+\end{minipage} & \begin{minipage}[b]{0.12\columnwidth}\centering
+How Many Foos\strut
+\end{minipage} & \begin{minipage}[b]{0.12\columnwidth}\centering
+How Many Bars\strut
+\end{minipage} & \begin{minipage}[b]{0.12\columnwidth}\centering
+Forbidden Float\strut
+\end{minipage}\tabularnewline
+\midrule
+\endhead
+\begin{minipage}[t]{0.12\columnwidth}\centering
+North America\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+94\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+20,028\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+17,465\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+12,084\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+20,659\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.71\strut
+\end{minipage}\tabularnewline
+\begin{minipage}[t]{0.12\columnwidth}\centering
+Central America\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+91\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+6564\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+6350\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+8,189\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+12,012\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.52\strut
+\end{minipage}\tabularnewline
+\begin{minipage}[t]{0.12\columnwidth}\centering
+South America\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+86\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+3902\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+4127\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+5,205\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+6,565\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.28\strut
+\end{minipage}\tabularnewline
+\begin{minipage}[t]{0.12\columnwidth}\centering
+Africa\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+84\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+2892\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+3175\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+3,862\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+4,248\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.1\strut
+\end{minipage}\tabularnewline
+\begin{minipage}[t]{0.12\columnwidth}\centering
+Europe\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+92\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+20,964\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+17,465\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+15,303\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+24,203\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.58\strut
+\end{minipage}\tabularnewline
+\begin{minipage}[t]{0.12\columnwidth}\centering
+Asia\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+87\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+6852\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+6350\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+8,255\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+11,688\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.47\strut
+\end{minipage}\tabularnewline
+\begin{minipage}[t]{0.12\columnwidth}\centering
+Oceania\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+87\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+4044\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+4127\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+5,540\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+6,972\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.28\strut
+\end{minipage}\tabularnewline
+\begin{minipage}[t]{0.12\columnwidth}\centering
+Antarctica\strut
+\end{minipage} & \begin{minipage}[t]{0.07\columnwidth}\centering
+83\%\strut
+\end{minipage} & \begin{minipage}[t]{0.09\columnwidth}\centering
+2964\strut
+\end{minipage} & \begin{minipage}[t]{0.14\columnwidth}\centering
+3175\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+4,402\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+4,941\strut
+\end{minipage} & \begin{minipage}[t]{0.12\columnwidth}\centering
+1.13\strut
+\end{minipage}\tabularnewline
+\bottomrule
+\end{longtable}

source/06_list_of_figures.md

@@ -1,5 +1,5 @@
 \listoffigures
-<!-- 
+<!--
 The \listoffigures will use short captions first, and the whole caption if none is present. To keep this list readable, ensure each figure has a short caption, e.g.
 ![main_text_caption](source/figures/my_image.pdf "short caption used in alt text and \listoffigures"){#fig:mylabel}{ width=50% }