# The LaTeX CGI Server

## Introduction

The LaTeX CGI server (currently running at latexcgi.xyz) accepts LaTeX documents via an HTTP POST request and returns a PDF document or log file in the case of error.

It is written as a perl script accepting the post requests via cgi-bin access in an apache HTTP server.

## HTTP Requests

The document must be supplied by an HTTP POST multipart/form-data request. Any other HTTP request is rejected. The allowed form fields are defined below. If the form contains unexpected fields, the whole submission is rejected.

## Form Fields

• engine

This field is optional, but if supplied must be one of `lualatex`, `pdflatex`, `xelatex`, `uplatex`, `platex` or the `-dev` variants such as `lualatex-dev`. The default is `pdflatex`.

• bibcmd

This field is optional, but if supplied must be one of `biber`, `bibtex`, `pbibtex`, `bibtex8`. It defaults to empty unless the log of the first run from LaTeX has a biblatex message saying to run biber or bibtex, or if there is a `No file document.bbl` message.

• filename[]

There must be at least one of these parameters, each specifying a filename. There must be one `filename[]` parameter with value `document.tex`

• filecontents[]

These multi-line fields contain the contents of the supplied files. There must be the same number of `filecontents[]` parameters as `filename[]` parameters.

• return

This field is optional but if supplied must be one or `pdfjs`, `pdf` or `log`.

The default is `pdfjs` meaning the PDF.js is used to render the PDF.

`pdf` specifies that the PDF document should be returned, so will use your browser’s default PDF renderer.

`log` specifies that the log file should be returned even in non-error cases.

• makeindex[]

This field is optional and may be used multiple times.

The value must be of the form `makindex` options

`options` gives the options for `makeindex` for the document `document.tex` it is currently restricted to `-` and `.` and ASCII letters and digits.

## The learnlatex Comment Interface.

Usually the form for the HTTP submission is generated by the `runlatex` JavaScript This constructs the parameters from one or more HTML `<pre>` elements, which may be controlled using comments of the form

``````% !TEX  ... keyword
``````

The comments are checked in a case insensitive way, any text other than the final keyword is ignored, so the following are all equivalent

``````% !TEX lualatex
%  !TeX  program = LuaLaTeX
% !tex  ignored comment lualatex
``````

The known keywords are

• `lualatex`, `pdflatex`, `xelatex`, `uplatex`, `platex`, `lualatex-dev`, `pdflatex-dev`, `xelatex-dev`, `uplatex-dev`, `platex-dev`

The `engine` parameter is set to the specified keyword (lowercased).

If this is not used then `engine` is set to `pdflatex`, unless `fontspec` appears in the example, in which case it is set to `xelatex`

• `biber`, `bibtex`, `pbibtex`, `bibtex8`

The `bibcmd` parameter is set to the specified keyword (lowercased).

If this is not used the `bibcmd` parameter is not set and bibtex or biber may be chosen automatically as described above.

• `pdfjs`, `pdf`, `log`

The `return` parameter is set to the specfied keyword (lowercased).

If this is not used, the `return` parameter is not set and the server will use PDF.js as described above.

• `makeindex` options

There may be any number of `% !TEX makeindex` comments, the options are passed to the LaTeX CGI server `makeindex[]` parameters described above.

## Processing Pipeline

1. Assuming the form fields are all validated, the supplied files are unpacked into a new temporary directory.
2. LaTeX is run on `document.tex` (using whichever engine is specified by engine parameter).
3. If there was an error, the log is returned and processing stops.
4. The log is searched for requests to run biber or bibtex, or to rerun latex.
5. If no “rerun” messages were found, the PDF is returned and processing stops.
6. If bibtex or biber is detected the relevant command as explicitly or implicitly specified in the bibcmd parameter is run.
7. If an error occurs in bibtex/biber, a log is returned (Currently this just has the exit status).
8. If any `makeindex[]` calls are specified these are run, if the previous command gave no error.
9. LaTeX is run twice more, checking for error after each run.
10. The PDF or error log is moved, and the temporary directory is deleted.
11. A PDF is returned, or the log file in case of error (or log requested).

Each system call is guarded by a timeout so “Error” in the above stages may be that the command was taking too long rather than an actual error. There are also restrictions on input paths for security reasons, attempting to input files out of the allowed area will result in `input error` being returned as the log, neither the TeX log nor the generated PDF will be returned.

The PDF document is not directly returned, the site hosts an instance of PDF.js and returns `PDF.js?file=document-xxxxx.pdf` primarily to ensure rendering in mobile clients that often do not include a PDF renderer by default.