Skip to content

Latest commit

 

History

History
91 lines (48 loc) · 6.34 KB

README.md

File metadata and controls

91 lines (48 loc) · 6.34 KB
Raw

The i-LaTeX editor

i-LaTeX is an extension that turns the Visual Studio Code editor into a prototypal editor for LaTeX featuring transitionals, visual representations of fragments of code that can be manipulated interactively by clicking their output in the generated PDF. The current version offers transitionals for mathematical formaluae, tables, images, and custom grid layouts.

Screenshot of VS Code running i-LaTeX

⚠️ At the moment, i-LaTeX only supports MacOS and Linux, and does not support Windows. If you are interested in adapting the extension to make it work with Windows, please contact us!

Installation

⬇️ Download the extension (.vsix) and the LaTeX package (.sty)

In order to use i-LaTeX, you must have the Visual Studio Code editor and a recent distribution of LaTeX (such as MacTeX or TeX Live) with latexmk installed on your system.

The extension is provided as a .vsix file that must be installed manually in Visual Studio Code, as explained in this guide.

The LaTeX package is provided as a .sty file that must be placed in the same directory as the LaTeX files that import it. Its purpose is explained below.

Usage

📖 Read the user guide for more detailed explanations

Compiling a document and displaying the generated PDF

In order to display a LaTeX document with i-LaTeX, you must (1) open the directory that contains all the files used by the document in Visual Studio Code and (2) open the main LaTeX document with i-LaTeX.

This last step can be performed by clicking the “i-LaTeX” button in the status bar, at the bottom of the editor's window, and either selecting the file that has the focus in the editor (Create from the active editor) or searching for the main LaTeX file of your document (Create from file...).

Once the file is selected, i-LaTeX will attempt to compile it. If the compilation fails, an error message will be displayed, and invite you to review the logs. If the compilation succeeds, the resulting PDF will be opened in a new panel. Once the PDF has been displayed, you can manually recompile the document by clicking the button displayed on top of the PDF.

Using transitionals

i-LaTeX currently features four kinds of transitionals, which require to use custom commands and environments in order to be detected by i-LaTeX. They are provided by the ilatex.sty package, which must be imported in your LaTeX document: put the file in the same directory, and use the \usepackage{ilatex} command.

The four transitionals are described in more details in the aformentioned manual. In a nutshell:

  • Use the imaths environment for mathematical formulae (instead of \[ … \], equation, align, etc)
  • Use the itabular environment for tables (instead of tabular)
  • Use the \iincludegraphics command for images (instead of \includegraphics, which has only one i!)
  • Refer to the manual for information on the custom grid layout environements (they are experimental!)

Elements with transitionals will be surrounded with blue halos and can be clicked to display the transitionals. The fragment of code represented by a transitional can be shown in the code editor by clicking the title bar of the transitional (with the name and the location of the code). When a transitional is closed, the document is automatically recompiled, unless there was no change in the code.

If the code cannot be parsed by i-LaTeX (e.g., because of a syntax error), an error message will be displayed. If the error is located within a fragment of code represented by a transitional that is currently visible, the transitional will be replaced by an error message. It should be restored as soon as the error is fixed, though in some cases, you might have to recompile the document.

Development

For technical details on how i-LaTeX works and how to extend it, such as for adding new kinds of transitionals, please refer to this technical guide.

Publications

i-LaTeX is a research prototype developed by Camille Gobert during his PhD in the ex)situ team (Paris-Saclay University, CNRS, Inria, Laboratoire Interdisciplinaire des Sciences du Numérique). You can read more about i-LaTeX and the underlying concept of transitional in the following papers:

Représentations intermédiaires interactives pour la manipulation de code LaTeX (Gobert & Beaudouin-Lafon, 2021), published at the IHM'20'21 conference (in French).

i-LaTeX: Manipulating Transitional Representations between LaTeX Code and Generated Documents (Gobert & Beaudouin-Lafon, 2022), to be published at the ACM CHI 2022 conference.

License and credits

The code of i-LaTeX is released under the MIT license. You can freely use and adapt the code of i-LaTeX, and we'd be glad to hear about it if you do!

However, the licenses of some dependencies may be more restrictive. In addition to the dependencies listed in package.json (such as Rollup for bundling the webview's code and Parsimmon for creating the parser), the webview of the extension uses a number of libraries that are not listed as dependencies and are currently part of the source code: