The TeXLive.net server (formally known as LaTeX CGI server and 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.
runlatex settings, as for learnlatex.orgThe 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.
engine
This field is optional, but if supplied must be one of
lualatex, pdflatex, xelatex, uplatex, platex, latex,
lualatex-dev, pdflatex-dev, xelatex-dev, uplatex-dev, platex-dev, latex-dev,
luatex, pdftex, xetex, uptex, ptex, tex,
optex,context,
asy.
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.
makeglossaries
This field is optional, but if supplied must be one of
makeglossaries, makeglossaries-light
It defaults to empty.
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, log or make4ht, LaTeXML or lwarp.
The default is pdfjs meaning that 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.
make4ht specifies that make4ht will be used and HTML
returned. If the engine is specified as xelatex or lualatex
then the -x or -l arguments respectively are passed to
make4ht so that it uses an appropriate TeX engine.
LaTeXML specifies HTML to be generated by LaTeXML (the engine parameter is ignored in this case).
lwarp specifies that HTML is to be generated by lwarpmk after generating PDF with the specified engine.
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.
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
lualatex, pdflatex, xelatex, uplatex, platex, latex,
lualatex-dev, pdflatex-dev, xelatex-dev, uplatex-dev,
platex-dev, latex-dev, luatex, pdftex, xetex,
uptex, ptex, tex, optex, context, asy.
The engine parameter is set to the specified keyword (lowercased).
If this is not used then engine is set to pdflatex.
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.
makeglossaries, makeglossaries-light.
The makeglossaries parameter is set to the specified keyword (lowercased).
pdfjs, pdf, log, make4ht, latexml, lwarp.
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 for PDF display, 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.
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.)
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 \ .
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.
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.
runlatex configuration object.runlatex.texts
An array of strings allowing site customisation and localisation.
runlatex.texts ={
"Open in Overleaf": "Overleaf button text",
"TeXLive.net": "texlive.net button text",
"Delete Output": "Delete Output button text",
"Compiling PDF": "Compiling PDF span notification of submission",
// The following not used on learnlatex.org
"edit": "edit button text",
"copy": "copy button text",
"Added Code": "Added code comment added to inserted code",
"End Added Code": "End Added code comment added to inserted code",
"Top Caption": "inline HTML caption added above the example:"
}
runlatex.editorlines=100;
The number of lines in the Editor.
runlatex.adddefaultpreamble=false;
If set true, a default preamble (using packages based on the
content of the fragment) will be inserted if the document has no
\documentclass
runlatex.adddefaultengine=false;
By default, runlatex will submit the example as pdflatex unless
there is a % !TeX luatex or similar comment. If this is set true
then the default engine is chosen based on commands or packages
used in the content.
If neither \documentclass nor a % !TeX engine comment appears in
the example then a default preamble is constructed (based on the
commands seen in the example) and added to the code block via the
ACE editor interface. This preamble may not be completely correct
as needed to run the example but is a good “first guess” and will
save typing boiler plate preambles in the online forum editor. If
the preamble is edited and re-submitted to the texlive.net server,
the boiler plate preamble is not re-added.
runlatex.usecaptions=false;
If this is true, and runlatex.texts['Top Caption'] is non empty
the caption will be inserted above each example.
runlatex.minrunlines=0;
If adddefaultpreamble is true, interaction is not added if there
are fewer than this number of lines. So for example setting this to
3 avoids adding a run latex button on 1 or 2 line fragments.
runlatex.usecookies=true;
The runlatex.js never sets any cookies but provides some helper
functions that may be used by hosting sites to set user
preferences. By default these cookies will be read if set to set
default return mechanims, default text engine and the theme used by
the ACE editor. If this option is set to false the functions just
return empty and no cookies will be accesed at all.
See the next section
runlatex.completionsURI=""
If this parameter is set to a non empty string, it is used as a URI to a JSON file that gives completion data for completing commands in the editor. See this example to see the format required. If it is an empty string then command completion is not enabled in the editor.
Curently if this parameter is used you also need to load the ACE extension
<script src="https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.12/ext-language_tools.js"></script>
(Perhaps runlatex.js should add this automatically when needed).
runlatex.packageregex = array of [regex, preamble code] pairs
If adddefaultpreamble is true this array is used to construct the
preamble. If the supplied fragment matches a regex, the associated
line (normally a \usepackage call) is added. A document could
supply the entire array but normally you just want to add
additional packages, so can extend the default array. For example
to add the siunitx package if \qty appears, you could declare:
runlatex.packageregex.push([/\\qty *[\[{]/, "\\usepackage{siunitx}\n"]);
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.
Two special !TEX comments may be used, which must be on the first
line. The comment marker for these does not need to be % it can be
any combination of %, #, /, *.
!TEX noedit causes the div to be left unchanged.
(equivalently class=noedit on the <pre> element).!TEX none causes the editor to be used in Text mode, and no
texlive.net button is added.
(equivalently class=norun on the <pre> element).If the the first non-white line does not start with % and does not
contain a \ then the no-compile, none mode is assumed, so that
log files, shell scripts etc may be inserted without being
interpreted as LaTeX.
document.tex (using whichever engine is specified by engine parameter).makeindex[] calls are specified these are run, if the previous command gave no error.dvipdfmx is called to generate PDF. For latex, dvips and ps2pdf are called to generate PDF.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.