\BlueLaTeX

Real-Time Collaborative Document Edition

View project onGitHub

Compiler API

This page describes how the paper compilation process is handled inside \BlueLaTeX.

Background Compilation

Paper compilation in \BlueLaTeX is performed as a background task. No user action is needed anymore.

This task is started when the first author joins the compiler resource of a paper. It is stopped when the last author leaves the compiler resource.

By joining the compiler resource of a paper, the author subscribes to an update stream that sends results of the compilation (either the compiled paper, or the error log).

Compilation Settings

Each paper may have specific compilation settings. These settings allow people to inform \BlueLaTeX how the compilation is to be performed:

  • compiler tells \BlueLaTeX which compiler to use to compile the paper (latex, pdflatex, xelatex, lualatex, …),
  • interval tells \BlueLaTeX how long (in seconds) it must wait between two recompilations,
  • timeout tells \BlueLaTeX after what timeout (in seconds) it must stops the current compilation pass, and (possibly) retry.
  • synctex tells \BlueLaTeX to generate SyncTeX data when compiling the paper.

Api Summary

Method Path Description
GET /<api>/compilers Get list of available compilers
GET /<api>/papers/<paperid>/compiled/pdf Get the compiled paper
GET /<api>/papers/<paperid>/compiled/log Get the compilation log
GET /<api>/papers/<paperid>/compiled/png Get the image rendering of the compiled paper
GET /<api>/papers/<paperid>/compiled/pages Get the number of pages in the compiled paper
GET /<api>/papers/<paperid>/compiler Get the compiler settings for the given paper
POST /<api>/papers/<paperid>/compiler Trigger compilation or register to compilation channel
PATCH /<api>/papers/<paperid>/compiler Modify the compiler settings
DELETE /<api>//papers/<paperid>/compiler Cleanup compilation directory
GET /<api>/papers/<paperid>/synctex Get the generated SyncTeX data

Get Compiler List

Mehtod: GET

Path: /<api>/compilers

Response:

Code Value Meaning
200 compiler list List of available compilers. An array of compiler names
401 error object User could not be authenticated
500 error object Something wrong happened on the server side

Get Compiled Paper

Mehtod: GET

Path: /<api>/papers/<paperid>/compiled/pdf

Response:

Code Value Meaning
200 pdf file The compiled pdf file
401 error object User has no right to see the compiled paper
404 error object No compiled pdf file was found
500 error object Something wrong happened on the server side

Get Compilation Log

Mehtod: GET

Path: /<api>/papers/<paperid>/compiled/log

Response:

Code Value Meaning
200 compilation log The compilation log file (text file)
401 error object User has no right to see the compilation log
404 error object No compilation log file was found
500 error object Something wrong happened on the server side

Get Png Rendered Page

Mehtod: GET

Path: /<api>/papers/<paperid>/compiled/png

Parameters:

Name Type Description
page int The page to render mandatory
density int The page rendering quality optional

Response:

Code Value Meaning
200 rendered png The requested page rendered as png image
401 error object User has no right to see the compiled paper
404 error object No rendered png file was found for the requested page
500 error object Something wrong happened on the server side

Get Number of Pages

Mehtod: GET

Path: /<api>/papers/<paperid>/compiled/pages

Response:

Code Value Meaning
200 int The number of pages in the compiled version
401 error object User has no right to see the compiled paper
404 error object No compiled pdf file was found
500 error object Something wrong happened on the server side

Get the Compiler Settings

Mehtod: GET

Path: /<api>/papers/<paperid>/compiler

Parameters:

Name Type Description
page int The page to render mandatory
density int The page rendering quality optional

Response:

Code Value Meaning Headers
200 compiler settings The compiler settings ETag contains the revision of the compiler settings (to be used when modifying them)
401 error object User has no right to see the compiler settings N/A
404 error object Compiler settings were not found N/A
500 error object Something wrong happened on the server side N/A

A compiler settings object is as follows: json { "compiler": "pdflatex", "timeout": 30, "interval": 15 }

Trigger Compilation

Mehtod: POST

Path: /<api>/papers/<paperid>/compiler

Response:

Code Value Meaning
200 true The paper was successfully compiled.
304 false The paper was not modified since last compilation and was not recompiled
401 error object User has no right to compile the paper
500 error object Something wrong happened on the server side
503 error object No compilation task is started

Depending on the server configuration, sending POST request to this resource either triggers a new compilation if none is already started (explicit compilation) or registers to the compilation channel (background compilation). In case of background compilation, the server answers when the last compilation ends. This uses long polling to notify client when the paper is compiled.

Modify the Compiler Settings

Mehtod: PATCH

Path: /papers/<paperid>/compiler

Headers: If-Match contains the revision of the compiler settings to modify (as returned in the ETag header)

Body: A Json Patch document as per RFC-6902 that modifies the compiler settings. A prerequisite is that the structure of the object must not be modified, only the values of standard fields (no new fields, no mandatory field removed, …)

Response:

Code Value Meaning Headers
200 true The compiler settings were successfully modified ETag contains the new revision of the compiler settings after modifications were applied
304 error object Not enough data were sent to perform modification N/A
401 error object User must be authenticated N/A
403 error object Not authorized to modifiy the paper data N/A
404 error object Compiler settings do not exist N/A
409 error object No revision or an obsolete revision was provided in the request N/A
500 error object Something wrong happened on the server side and the action could not be performed N/A

Cleanup Compilation Directory

Mehtod: DELETE

Path: /<api>//papers/<paperid>/compiler

Response:

Code Value Meaning Headers
200 true The compilation data were successfully removed  
401 error object User must be authenticated N/A
403 error object Not authorized to modifiy the paper data N/A
500 error object Something wrong happened on the server side and the action could not be performed N/A

Get SyncTeX data

Mehtod: GET

Path: /papers/<paperid>/synctex

Response:

Code Value Meaning Headers
200 gziped synctex file The generated SyncTeX data Content-Type is application/gzip
401 error object User has no right to see the SyncTeX data N/A
404 error object No compiled SyncTeX file was found N/A
500 error object Something wrong happened on the server side N/A