latexcgi

The TeXLive.net Server

Introduction

The TeXLive.net server (formally known as (LaTeX CGI server) (currently running at texlive.net) 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.

Example Documents

Files with default runlatex settings, as for learnlatex.org

Files with parameter settings similar to latex.org or texwelt.de.

Testing command completion

Files testing HTML output.

Generate URI corresponding to examples.

Tutorial site using this server

LaTeX Forums using this 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

The learnlatex Comment Interface (runlatex.js)

Usually the form for the HTTP submission is generated by the runlatex JavaScript, runlatex.js, jointly maintained at the learnlatex Github.

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

No Edit Option

If an HTML <pre> element has the CSS noedit class then it is not processed by this JavaScript and the original <pre> is displayed. (In GitHub pages the markup {: .noedit :} may be placed after the code block to add this class.)

No TeX compilation

If an HTML <pre> element has the CSS norun class the buttons to submit the example is not added.

By default, when adddefaultpreamble parameter is false if the code block does not contain either \documentclass or a % !TEX comment that specifies a TeX engine, no buttons are added to submit the document to an online TeX system.

If the adddefaultpreamble parameter is true, then the buttons are added if the example has more than minrunlines, and the first line starts with % or contains a \ .

Multifile Projects.

Normally just the file corresponding to a single code block is submitted but the page may contain a javascript preincludes array that specifies a mapping of code blocks to filenames to control a multi-file submission to either texlive.net or Overleaf.

See LearnLaTeX lesson 13.

runlatex Parameters

A page loading runlatex.js can set several parameters as fields in the runlatex configuration. Many of these parameters were added to allow customisation for use in forums such as latex.org or texwelt.de managed by Stefan Kottwitz. Unlike the situation with curated examples in a tutorial such as learnlatex, forums often have incomplete or erroneous examples, and a slightly different interaction is required.

The runlatex configuration object.

Setting default parameters via cookies.

By default no information is stored in cookies or other local storage and so each submission is controlled just by the comments in the code to be submitted. It is however possible to save alternative default values for the engine, return and ACE theme from their initial values of pdfjs, pdflatex and textmate.

A sample form to set these cookies is available on this site.

Note that the cookies are browser and site specific so a value set on this site will not affect another site using the same code.

If site maintainers using copies of runlatex.js wish to use the cookie settings they may want to adjust the setting form. In particular, if your site already has a global cookie acceptance mechanism, you may want to not have the accept/delete buttons and instead enable the options automatically if the user has already accepted cookies for your site.

Code blocks without TeX submission

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. For pLaTeX variants dvipdfmx is called to generate PDF. For latex, dvips and ps2pdf are called to generate PDF.
  11. The PDF or error log (or for HTML returns, the output directory) is moved, and the temporary directory is deleted.
  12. A PDF (or for HTML return options the top level HTML file) 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.


privacy policy
Copyright 2020–2021 David Carlisle