Skip to content

For Developers

Info

This page is a draft as the project is still in an early development stage. Informations here might drastically change. Once near completion, this section will be filled with the necessary information to build, debug, test and mantain the project.

As a general overview, the project is structured as follows:

  • Each LaTeX repository has two pipelines, one for compiling the project (latex.yml) to pdf and one other to create and publish the web version (web.yml).
  • The code for compiling the project is self-contained in the LaTeX GitHub action.
  • The code for creating and publishing the web version is contained in the eisa-web-report repository.
  • The project is built in Python 3.13 and Docker.
  • The web version of the report is currently static, but we are exploring Flask as a possible web framework.
  • We are converting LaTeX to HTML (more on the next section) and then applying on top of it custom CSS and JS.
  • We are using lunr.js for the search functionality.
  • We are using latex.css for the CSS.
  • We are also using bootstrap for the CSS.
  • We are aware of a routing problem (i.e. pages appear as main-domain.cern/volume2.html instead of main-domain/chapter-title.html), this is a known issue and we are working on it. However as SEO is not a priority for this project, this is not a blocker.

From LaTeX to HTML

There are several tools available to convert LaTeX to HTML. Some of the most popular are:

  • TeX4ht: This is a versatile program supporting LaTeX or Plain TeX. It uses DVI files and can render math through bitmaps or other methods. While setting it up can be intricate, make4ht offers a simplified interface for working with tex4ht.

  • LaTeXML: Developed by NIST, LaTeXML is a Perl-based tool that parses a wide range of TeX code, including complex macros. It’s used in the web version of the DLMF and is available via the NIST site, though it’s not typically bundled with standard TeX distributions.

  • lwarp: This tool translates TeX to HTML through LaTeX, LuaLaTeX, or XeLaTeX and doesn’t require external tools like make or gawk. It also supports xindy and latexmk for indexing and automation.

  • LaTeX2HTML: A widely-used Perl tool for LaTeX-to-HTML conversion, it produces bitmap images for mathematical expressions and other complex content. Originally developed for Unix, it now runs on various platforms.

  • Hevea: This Objective CAML-based converter supports LaTeX and uses font and table methods for equations, similar to TtH. It’s available from INRIA rather than CTAN.

  • TtH: This tool can handle LaTeX or Plain TeX using font and table techniques for math rendering. It’s notably fast, though the HTML it produces may not align with current standards.

  • plasTeX: This Python framework for LaTeX documents provides DOM-style access, supporting outputs in formats like HTML and DocBook.

We tried all of them, and decided to go for TeX4ht as it is the most versatile and the one that best fits our needs. We are using make4ht as a simplified interface for working with tex4ht.

We spent a significant amount of time to try to make LaTeXML work, this is because it is the tool used by ArXiv to convert LaTeX to HTML. However, we found difficult to adapt it to our needs, as it is not as versatile as TeX4ht.

Workflow

Below you can find a scheme of the workflow of the tool.

stateDiagram-v2
    [*] --> Overleaf
    Overleaf --> GitHubRepo: Syncs with

    GitHubRepo --> GeneratePDF: on Push
    GeneratePDF --> PDFAvailableToDownload

    GitHubRepo --> ConvertToHTML: on Push
    ConvertToHTML --> IntegrateIntoHugo: Integration chapter by chapter into Hugo
    IntegrateIntoHugo --> ApplyReportMetadata: Apply the metadata
    GitHubRepo --> ApplyReportMetadata: Retrieves metadata

    ApplyReportMetadata --> GenerateDockerImage: Generate Docker image from the GitHub pipeline
    GenerateDockerImage --> DeployOnCernRegistry: Deploy on CERN Docker Registry
    DeployOnCernRegistry --> OpenShiftPull: Openshift auto-pulls image
    OpenShiftPull --> CERN_TLD: CERN TLD assigned to Openshift instance