diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100644 index 00000000..4eb944a0 --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,7 @@ + + + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100644 index 00000000..2def2a7c --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/phd_thesis_markdown.iml b/.idea/phd_thesis_markdown.iml new file mode 100644 index 00000000..7c9d48f0 --- /dev/null +++ b/.idea/phd_thesis_markdown.iml @@ -0,0 +1,12 @@ + + + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100644 index 00000000..94a25f7f --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..7d954a04 --- /dev/null +++ b/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"] diff --git a/Makefile b/Makefile index f000825c..6873f3bf 100644 --- a/Makefile +++ b/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 diff --git a/README.md b/README.md index 9c789fa4..e7747621 100644 --- a/README.md +++ b/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? diff --git a/install.sh b/install.sh new file mode 100644 index 00000000..e9a4b39d --- /dev/null +++ b/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 diff --git a/output/source/figures/example_figure.pdf b/output/source/figures/example_figure.pdf deleted file mode 100644 index dcffff1d..00000000 Binary files a/output/source/figures/example_figure.pdf and /dev/null differ diff --git a/output/thesis.html b/output/thesis.html index 176f805a..abe9bf39 100644 --- a/output/thesis.html +++ b/output/thesis.html @@ -5,9 +5,72 @@ - + 01_title_page - +