quicklatex

This program was written to enable me to write my lecture notes and all other stuff related too me studying mathematics in LaTeX. As LaTeX is at times to verbose to write as quickly as a lecturer can on a black board, this program makes some simplification to help me.

quicklatex is based on pdflatex and acts as a wrapper around it. Most features are optional, so you can write QLX ("QLX" is my name for the LaTeX-derived file format this program uses and is short for "quick latex") that is pretty similar to LaTeX (useful in the beginning, but in the long term you will presumably want to use all/most features). Due to that similarity I'll need to know LaTeX and I will presume that you do.

Installation

To install quicklatex, please first ensure that pdflatex is installed and available. Then there are two ways to install quicklatex:

• Manually:

   git clone https://codeberg.org/zvavybir/quicklatex.git
   cd quicklatex
   cargo build --release
   cp target/release/quicklatex ~/bin
  

  If you don't want to install it in ~/bin, just replace the last line with the correct one (or remove it to not install it at all).

• Using Rust's package manager cargo:

   cargo install quicklatex
  

Usage

To use the program just call it with the file name as you would pdflatex:

quicklatex [OPTIONS] FILE [COUNT]

Explanation:

• Options:
  • -p or --profiling: Activates profiling. This prints out the time various parts of quicklatex took. Probably not necessary if you're not a quicklatex developer.
• File: The file name can be the actual file name or – if the name ends in .tex – with the .tex, tex, or ex left out (so if you have a file my_notes/math.tex you could also use e.g. my_notes/math.t).
• Count: By default (if this argument is not given) quicklatex will only run pdflatex once per invocation, but LaTeX famously needs multiple invocations sometimes. You could do this by manually evoking quicklatex as you're used to, but this is more convenient and only has to convert from QLX to LaTeX once. COUNT needs to be a non-negative integer.

The program outputs to the terminal the transformed LaTeX, pdflatex's output, and – if applicable – all generated warnings very flashy (the warnings get outputted both at the beginning and the end).

quicklatex for LaTeX

Currently quicklatex only supports LaTeX. It might support Typst at some point.

Minor features

There are a couple minor features:

• Auto newlining in math mode. In environments whose name starts with "align" (like align and align*) double backslashes ("\\") are automatically added at the end of lines. You can of course still make them manually anywhere (which doesn't interfere with this feature) or add an % at the end of the line to comment it out.
• quicklatex stops processing at the "𝇞" character and silently throws away anything afterwards, so if you include one of them in your file you have some space to put scibbles/… that you don't want pdflatex to see (because e.g. there malformed LaTeX or because shouldn't end up in the PDF).

QLR files & custom replacements

Alongside of QLX files (which are the files you write your actual LaTeX-ish source code in) there are also QLR files (short for "quicklatex replacement") which are the config files for quicklatex.

The QLR file that is used in a specific case is determined as follows:

• quicklatex checks if there is a file with the same name as the file that should be built except for the extension .qlr and if it finds it uses that one. So if you try to build my_notes/math.tex, quicklatex looks for a file with the name my_notes/math.qlr.
• If that fails it tries to use ~/.zvavybir/quicklatex/default.qlr.
• If that file also doesn't exist, it just uses no file.

The format of the QLR files is pretty restrictive. On each line there must be exactly one command, which consists out of the command name, a space, and a semicolon seperated list of arguments. The arguments itself are arbitrary (as long as they don't contain newlines, semicola, or malformed escape sequences) and you can use the following escape sequences there:

• \\: A literal backslash.
• \;: A semicolon. These are necessary to distinguish them from the argument seperator.
• \n: A newline character.
• \s: A space character. Arguments can also contain literal spaces, but that's often not advisable for readability purposes, so there is this other option.

All commands are run one-after-the-other on the whole file (except refkind ones, as later explained).

There are a bunch of command names, falling in two categories:

• The replacement commands: The base form of a replacement command is replace FROM;TO with FROM and TO being arbitrary. This command simply replaces all occurences of FROM with TO (at once, so if TO contains FROM or similar it's not run again; see _repeated for that below), no matter whether that looks sensible to LaTeX (i.e. it's non-hygienic, which is exactly the thing that makes quicklatex so useful). To illustrate this, let's look at the following QLR file (instead of the spaces around that "+" we could of course also have used the \s escape sequence):

  replace \\frac{a}{;1
  replace b}; + 2
  

  This would replace \frac{a}{b} to 1 + 2 and \frac{a}{5 b} to 15 + 2.

  It is generally advisable to make sure that other replacement rules and LaTeX tokenization don't interfere with that rule. The probably most important part of that is that I usually add a space (or more precisely a \s) at the end of a LaTeX command substitution (so for example I want ð to be the fraction command, so I use the replacement rule replace ð;\\frac\s, not replace ð;\\frac).

  The following four suffixes can be added to "replace" to make other command names with other functionality (these are arbitrarily combinable and the order doesn't matter, so e.g. replace_noisy_conditionally and replace_conditionally_noisy is the same thing):

  • _noisy: If such a replacement rule is triggered quicklatex outputs a big warning at the beginning and end of it's terminal output saying which it was. This is useful to temporarily fix typos (e.g. I often mistype \approx as \apporx, so I have the replace_noisy \\apporx;\\approx rule).
  • _repeated: This runs the replacement many times (until nothing would change anymore anyway or a recursion was detected). I don't know why I implemented that because it's only so rarely useful that I can't find a single time I used it.
  • _conditionally: This command takes a third argument and is only then run if this argument is present anywhere in the file at the time the command is run. Say we have a file with abc in it and the QLR file is as follows:

    replace c;xyz
    replace_conditionally a;123a;yz
    

    The first command yields abxyz and the second makes it 123abxyz. Without the first command it would stay at abc, despite there being an a that could be replaced.
  • _refkind: These commands are special because they runs after all non-refkind ones (but still before later refkind ones) and replace_refkind FROM;TO replaces FROM\ref (instead of FROM) with TO. Otherwise though they are normal (especially this means that "refkind" can be combined with the other suffixes (apart from _repeated, which here doesn't do anything) as usual). These are useful if you refer to labels with something else than LaTeX's \ref command.

• The include commands: The base form of an include command is include FILE with FILE being the file that is included (relative paths are evaluated relative to the file that has the include command). Since QLR doesn't have variables or similar there is only one sensible way that inclusion could work (i.e. the command is replaced by the contents of the file (or any equivalent phrasing)), so quicklatex does that one.

  If you add the _default suffix (i.e. use include_default FILE), quicklatex doesn't search relative to the including file, but relative to ~/.zvavybir/quicklatex. I tend to have one ~/.zvavybir/quicklatex/COURSENAME.qlr file (which contains at least the line include_default default.qlr[^10]) for each course I take and then use include_default COURSENAME.qlr in the QLR file of each file I'm writing for that course.

Labels

quicklatex automatically checks if labels are in the correct order, duplicated, or non-existent and removes unused ones. For the first point quicklatex expects each label to consist out of a consitent number of numbers (the numbers can be of any sign and can be fractional) seperated by colons, and warns otherwise.

For the last two points quicklatex needs to be able to automatically figure out which labels exist and which are used. For this it expects labels to be declared as \label{LABEL} and used as \ref{LABEL}. To not remove labels that are referred to exclusively by LaTeX commands that aren't \ref there are the _refkind replacement commands. As explained above the rule replace_refkind FROM;TO replaces FROM\ref with TO. For example to use custom text in a reference (i.e. LaTeX command \hyperref[LABEL]{TEXT}) I have the replacement rule replace_refkind hyper;\\hyperrefzvav and in a LaTeX package the command definition \newcommand{\hyperrefzvav}[2]{\hyperref[#1]{#2}}, which I then use with hyper\ref{LABEL}{TEXT}.

Unused labels aren't considered an issue, but wrongly ordered, duplicated, and non-existent ones are, so quicklatex will output a flashy warning for these. It might be important to note here though that some warning obscure others (after all, one warning already means that's something is out of wack, so it doesn't always even make sense to say what is supposed to happen otherwise), but if there are issues you will always get at least one warning out (although maybe not the multiple ones that would be appropriate).

Short brackets

There are a lot of brackets used in LaTeX and at least for me the typing required for that (especially for the going back after you have the closing one) is a bit annoying, so quicklatex makes small brackets easier to type by front-loading all the typing. To use this in practice, you type one or two characters specifying the length of the contents of the brackets, one character for what kind it is, and the the content.

The following lengths are available (all typed via AltGr+Number on a normal Linux keyboard layout):

• ¹: One character.
• ²: Two characters.
• ³: Three characters.
• ¼: Four characters.
• ½: Five characters.
• § + Digit or Letter: As many characters as specified in the digit or letter (letters go a being 10, b being 11, and so forth till z being 35).

The following bracket kinds are supported:

• (a space), c, {, or }: Curly brackets.
• p, (, or ): Inserts ł( as opening bracket and ¶) as closing bracket.
• q, [, or ]: Inserts ł[ as opening bracket and ¶] as closing bracket.
• a, or |: Inserts ł| as opening bracket and ¶| as closing bracket.
• i, or .: Inserts ł. as opening bracket and ¶| as closing bracket (yes, opening and closing are intentionally different; that's not a typo).

Apart from the first they all rely on my replacement rules replace ł;\\left\s and replace ¶;\\right\s. To use any of those short brackets you will need some rules to deal with "ł" and "¶", even if you might want to use some other short-form for \left and \right.

Contributing

quicklatex can always be improved and new use cases devised, so if you have an idea, found a bug, or something else please feel free to open an issue or open a pull request (PR), or contribute otherwise.

License

quicklatex is licensed under the GNU Affero General Public License version 3 or any later.

General tips for writing LaTeX quickly

I want to end by giving a tip that more generally applies to writing LaTeX (or anything similar) quickly, even if you don't use quicklatex: Don't insist on "proper" form that isn't necessary for readability, especially if it's annoying to type. If, for example, I want to write a half, I'm not writing it \frac{1}{2}, but ð12 (or \frac12 in raw LaTeX, without my replace ð;\\frac\s rule). Because I now have nearly three years of experience with reading that, it's nearly as intuitive as \frac{1}{2} or "½".

[^10] In this case (because the including file is already in ~/.zvavybir/quicklatex the "_default" suffix would be unnecessary, but it feels clearer.)