lgdock is a tool for preparing LaTeX papers. It depends on having Docker installed on a host, and also works with boot2docker.
To start, you can clone this repository or otherwise drop the gradle-related files into your paper's directory:
- gradlew
- gradlew.bat
- gradle/
- build.gradle
- gradle.properties
Docker is used to isolate the execution of LaTeX in a container, and Gradle is used to wrap tasks into a pretty nice interface (perhaps that's debatable ... but I like it).
You will need to have Docker installed and a Docker daemon running on your machine. Your Docker installation will need to expose its HTTP interface. If you are using boot2docker on a Windows or Mac computer, this is the default configuration. If you are on a Linux host with Docker directly installed, check out this blog post, and if you are on a systemd- based system, check this comment under said blog post.
Once you have Docker installed, you need to tell gradle where to find Docker and your LaTex file:
- base: the base name to use for you final LaTex files
- dockerUrl: the path to your URL, including protocol, host, and port (e.g., https://192.168.59.103:2376)
- source: Your LaTeX input file
The script uses Gradle properties for this. You can use the provided gradle.properties file to define them (with gradle.properties living in your working directory) OR just set properties from the command line like so:
gradle-Pbase="example" -PdockerUrl="https://..." ...
With these properties set, you can now run tasks on the given sample files. A simple build of a PDF currently requires running two tasks explicitly. (Hopefully, these can be safely linked in the future!)
./gradlew buildImage
./gradlew buildPaper
The buildImage task pulls down the supporting Docker base image and installs LaTeX packages. This task will take some time, especially if you have a slow Internet connection. You don't typically need to repeat this task (only when you modify the inline Dockerfile built into the build.gradle script).
The buildPaper task will produce "example-single.pdf" in your current directory, which is your finalized document. The input file "example.tex" is used as input, corresponding to the value of the "base" property. Prior to running LaTeX, the input file is processed for any "\input" entries, producing a "base-single.tex" variant.
Available tasks are:
- buildImage - build the base Docker image
- buildPaper - Run the sequence of pdflatex, bibtex, pdflatex, pdflatex to generate a PDF with optional bibliography (will also run singleFile)
- cleanAll - remove paper files and the Docker image. NOT recommended unless you are tweaking the image
- cleanPaper - remove intermediate paper files
- generateFigure - generate a LaTeX figure block, given an image
- generateTable - generate a LaTeX table block, given a CSV file of raw data
- runRscript - run an R script and save output
- singleFile - produce a single LaTeX file from a file which uses "input" commands
The Dockerfile is defined inline in the build.gradle script. It installs a basic set of texlive packages and R statistics packages. The Gradle tasks run some commands locally and some within Docker containers.
When running in Docker containers, the current directory is mounted as the location "/papers" in the container thanks to a Volume.
I am using the docker-java library to communicate with the Docker host over its Remote API.
To extend this setup, just define additional tasks in the build.gradle script. If you want to run a new LaTeX or R command, you should check out the doCmd helper function in the Gradle script, which runs a given String as a command in the Docker container.
If you need to install additonal dependencies in the Docker container, look at the multi-line String defined as "dockerfileContent". You'll see several examples of installing Ubuntu packages. Note that after any modifications to this String, you will need to run buildImage.
It may seem like Gradle and Docker are much heavier dependencies than the likes of LaTeX and R. First, I'm not 100% sure that's the truth, because LaTeX distributions tend to be HUGE and their packages (especially away from Linux platforms) interweaved. However, I still like the portability of having a known LaTeX and R setup that goes with me. Also, boot2Docker is very easy to install, and affords users the ability to use these tools in their more natural *nix environment without having to remember all of the quirks by hand.
I think this could be a pretty useful tool for making LaTex and R more usable. It's my plan to continue to expand the tasks available here as I have a need for them myself.
I probably won't have time to make things and pretty and robust as I'd like, as I'm currently working full-time on top of working on dissertation research. If you do have ideas or questions, feel free to post an issue or send me a Pull Request.
Thanks for stopping by!