README.md

Многоꙮтех

Многоꙮтех (mnogootex) is a utility that parallelizes compilation of a LaTeX document using different classes and offers a meaningfully filtered output.

The motivating use case is maintaining a single preamble while submitting a paper to many journals using their outdated or crummy document classes.

Getting started

Prerequisites

Многоꙮтех is written in Ruby and requires version >=2.5 (earlier ones are untested). You can check whether it's installed by running ruby --version. For installation instructions you can refer to the official documentation.

Многоꙮтех heavily relies on latexmk. You can check whether it's installed by running latexmk --version. If you are missing it, follow the documentation of your specific LaTeX distribution and install the latexmk package.

Installation

To install многоꙮтех execute

gem install mnogootex

If you're upgrading from a previous version, execute

gem update mnogootex

and remove any mention of mnogootex from your shell profile (it's not needed anymore).

Quick start

First you write a LaTeX document:

% ~/demo/main.tex
\documentclass{scrarticle}
\begin{document}
  \abstract{Simply put, my article is awesome.}
  Let's port my \KOMAScript\ article to other classes!
\end{document}

Then you list the desided classes in a Многоꙮтех configuration file:

# ~/demo/.mnogootexrc
jobs:
  - scrartcl
  - article
  - book

Finally you run mnogootex build and enjoy the technicolor:

Usage

A Многоꙮтех run does the following:

1. copy the source folder of a project to many target folders, one for each job;
2. replace the document class in the source of each target folder with the name of the relative job;
3. call latexmk in parallel on each target folder to compile the documents (or do other tasks);
4. wait for the outcomes and print the logs, filtered and colour-coded in a meaningful way.

Its convenience lies in the fact that it

• automates the setup process,
• parallelizes compilation,
• improves the readability of the infamous waterfall logs.

Многоꙮтех can be invoked from CLI using mnogootex. It accepts various commands detailed below.

To leverage the full power of this tool you will need to learn writing mnogootex configurations and 'latexmk' configurations. It might sound daunting but they're really just a few lines.

mnogootex commands

Notation: [FOO] means that FOO is optional while FOO ... means one or more FOOs.

All commands except help accept the same parameters, so let's examine them in advance to avoid repeating ourselves later. Here is their syntax:

mnogootex COMMAND [JOB ...] [FLAG ...] ROOT

JOBs are the names of the document classes to compile your document with. Zero or more can be provided, and when none is given the job list is loaded from the configuration.

FLAGs are latexmk options. Zero or more can be provided to override the behaviour of the latexmk call underlying the mnogootex command. You can obtain a list of available options with the inline help latexmk --help, and the full documentation with man latexmk. Generally speaking, if you find yourself always using a FLAG you should properly configure latexmk instead.

The last mandatory parameter is the ROOT file for compiling of your document.

Let's examine the details of each command now.

help [COMMAND]

This command prints the help for COMMAND (or all commands if none is given).

exec [JOB ...] [FLAG ...] ROOT

This command simply runs latexmk on the ROOT document for each of your JOBs passing the given FLAGs.

All other commands below are specializations of this one. However you'll seldom use it unless you're debugging.

build [JOB ...] [FLAG ...] ROOT

This command builds your document.

It is equivalent to exec [JOB ...] -interaction=nonstopmode ROOT.

You will probably need to pass some FLAGs (e.g. to use the correct engine) but it is not recommended: configure latexmk instead.

open [JOB ...] [FLAG ...] ROOT

This command opens the final compilation artifact (after running the build if necessary).

It is equivalent to exec [JOB ...] -pv -interaction=nonstopmode ROOT.

You might need to pass some FLAGs (e.g. to use the correct viewer) but it is not recommended: configure latexmk instead.

clean [JOB ...] [FLAG ...] ROOT

This command deletes all nonessential build files while keeping the compiled artifacts.

It is equivalent to exec [JOB ...] -c ROOT.

clobber [JOB ...] [FLAG ...] ROOT

This command deletes all nonessential build files including the compiled artifacts.

It is equivalent to exec [JOB ...] -C ROOT.

mnogootex configuration

mnogootex is configured through YAML files named .mnogootexrc put into your projects' root directory.

When mnogootex loads a configuration it also looks up for .mnogootexrc files in all parent directories to merge then together (from the shallowest to the deepest path). This means that e.g. you can keep a configuration file in your home folder and use it as a global configuration for all you projects, while overwriting only specific options in the configuration files of each one.

mnogootex currently accepts three options.

jobs

This option represents the JOBs to build your document (when none are given via CLI).

It must contain valid document class names, given as a list of strings.

By default there are no JOBs:

# Default value:
jobs: []

Here is a slightly more interesting example:

jobs:
  - scrartcl
  - article
  - book

work_path

This option is the folder where all elaboration happens.

It must be a well formed path, given as a string.

By default none is given, meaning that each run of any given job happens in a dedicated temporary folder:

# Default value:
work_path: null

Overriding this allows you to have easier access to the compilation artifacts. A good choice is setting it to ./build and keep everything below your source folder:

work_path: ./build

spinner

This option is the spinner animation shown by the CLI.

It is a series of frames given as characters of a string.

By default it's a hole looping around in a blister:

# Default value:
spinner: ⣾⣽⣻⢿⡿⣟⣯⣷

Here is a couple more in case your terminal doesn't like Unicode:

# A wriggly ASCII worm:
spinner: )}]|[{({[|]}
# An extended ASCII boomerang:
spinner: ╒┍┌┎╓╖┒┐┑╕╛┙┘┚╜╙┖└┕╘

Feel free to get creative!

latexmk configuration

latexmk is configured through Perl files named .latexmkrc put into your projects' root directory.

When latexmk loads a configuration it also looks up for .latexmkrc files in all parent directories to merge then together (from the shallowest to the deepest path). This means that e.g. you can keep a configuration file in your home folder and use it as a global configuration for all you projects, while overwriting only specific options in the configuration files of each one.

latexmk has a gazillion of options. We'll just skim over the most common ones here.

First of all, one must pick the correct engine. Assuming you want to produce a PDF artifact, you have a few choices:

$pdf_mode = 1; # create PDF with pdflatex
# $pdf_mode = 2; # create PDF with ps2pdf (via PS)
# $pdf_mode = 3; # create PDF with dvipdf (via DVI)
# $pdf_mode = 4; # create PDF with lualatex
# $pdf_mode = 5; # create PDF with xelatex

Then, if your PDF previewer is not being detected, you might need to configure it. Assuming you want to use evince:

$pdf_previewer = 'start evince';

Most people won't probably need anything more than that. However, for further details read the documentation in the commandline with man latexmk or on CTAN

Acknowledgements

• Thanks to @tetrapharmakon for being the first tester and user.