Add support for glossary (#592)

* Add glossary

* working changes

* Remove useless comment

* Add initial changes to build glossaries (not complete as we need to connect the export system to the rest of the application and instruct in the options when the make of glossaries is necessary)

* Add build for glossaries. Build command works and glossary is present in the final PDF, but there are still some errors raised

* Do not raise error when glossary node is encountered

* Do not build glossaries while extracting parts. This commit makes the change 'complete'. The code is not perfect though and needs a couple improvements

* Apply feedback from review and remove TEX rendering from jtex to myst-to-tex

* Fix linting issues

* Remove wrong comment

* Fix empty glossary preamble case, a string+undefined results in 'undefined' being appended

* Redirect output to logfile when running makeglossaries command

* Better empty object check

* Fix typo

* Bette newline handling

* Simplify logic around term and definition text extraction

* Fix extra space in output

* Fix additional undesired newline when rendering glossary terms without referecnes

* Add tests for glossaries

* Add changeset

* Add test for parts

* Fix lint format

* Fix failing tests in myst-cli

* Fix linting issues

.changeset/wise-grapes-tell.md

@@ -0,0 +1,8 @@
+---
+'myst-common': patch
+'myst-to-tex': patch
+'myst-cli': patch
+'jtex': patch
+---
+
+Added support for glossaries and TEX/PDF export. Now it is possible to render glossaries in TeX and PDF documents.

packages/jtex/package.json

@@ -51,6 +51,7 @@
     "myst-cli-utils": "^2.0.3",
     "myst-frontmatter": "^1.1.5",
     "myst-templates": "^1.0.8",
+    "myst-common": "^1.1.5",
     "node-fetch": "^3.3.1",
     "nunjucks": "^3.2.4",
     "pretty-hrtime": "^1.0.3",

packages/jtex/src/export.ts

@@ -1,11 +1,27 @@
+import path from 'node:path';
 import type MystTemplate from 'myst-templates';
 
-export function pdfExportCommand(texFile: string, logFile: string, template?: MystTemplate) {
+export function pdfExportCommand(
+  texFile: string,
+  logFile: string,
+  template?: MystTemplate,
+): string {
   const templateYml = template?.getValidatedTemplateYml();
   const engine = templateYml?.build?.engine ?? '-xelatex';
-  if (process.platform === 'win32') {
-    return `latexmk -f ${engine} -synctex=1 -interaction=batchmode -file-line-error -latexoption="-shell-escape" ${texFile} 1> ${logFile} 2>&1`;
-  } else {
-    return `latexmk -f ${engine} -synctex=1 -interaction=batchmode -file-line-error -latexoption="-shell-escape" ${texFile} &> ${logFile}`;
-  }
+  const baseCommand = `latexmk -f ${engine} -synctex=1 -interaction=batchmode -file-line-error -latexoption="-shell-escape" ${texFile}`;
+
+  return createCommand(baseCommand, logFile);
+}
+
+export function texMakeGlossariesCommand(texFile: string, logFile: string): string {
+  const fileNameNoExt = path.basename(texFile, '.tex');
+  const baseCommand = `makeglossaries ${fileNameNoExt}`;
+
+  return createCommand(baseCommand, logFile);
+}
+
+function createCommand(baseCommand: string, logFile: string): string {
+  return process.platform === 'win32'
+    ? `${baseCommand} 1> ${logFile} 2>&1`
+    : `${baseCommand} &> ${logFile}`;
 }

packages/jtex/src/imports.ts

@@ -1,17 +1,9 @@
 import type { TemplateImports } from './types.js';
+import { writeTexLabelledComment } from 'myst-common';
 
-const commentLenth = 50;
+const commentLength = 50;
 
-function label(title: string, commands: string[]) {
-  if (!commands || commands?.length === 0) return '';
-  const len = (commentLenth - title.length - 4) / 2;
-  const start = ''.padEnd(Math.ceil(len), '%');
-  const end = ''.padEnd(Math.floor(len), '%');
-  const titleBlock = `${start}  ${title}  ${end}\n`;
-  return `${titleBlock}${commands.join('\n')}\n`;
-}
-
-export function createImportCommands(commands: Set<string>, existingPackages?: string[]) {
+export function createImportCommands(commands: Set<string>, existingPackages?: string[]): string[] {
   const sorted = [...commands].sort();
   const existingSet = new Set(existingPackages);
   const filtered = existingPackages ? sorted.filter((p) => !existingSet.has(p)) : sorted;
@@ -33,11 +25,19 @@ export function renderImports(
 ): string {
   if (!templateImports || typeof templateImports === 'string') return templateImports || '';
   const packages = new Set(templateImports.imports);
-  const imports = label('imports', createImportCommands(packages, existingPackages));
-  const commands = label('math commands', createMathCommands(templateImports.commands));
+  const imports = writeTexLabelledComment(
+    'imports',
+    createImportCommands(packages, existingPackages),
+    commentLength,
+  );
+  const commands = writeTexLabelledComment(
+    'math commands',
+    createMathCommands(templateImports.commands),
+    commentLength,
+  );
   const block = `${imports}${commands}`;
   if (!block) return '';
-  const percents = ''.padEnd(commentLenth, '%');
+  const percents = ''.padEnd(commentLength, '%');
   return `${percents}\n${block}${percents}`;
 }
 

packages/jtex/src/jtex.ts

@@ -40,6 +40,7 @@ export function renderTex(
     bibliography?: string[];
     sourceFile?: string;
     imports?: string | TemplateImports;
+    glossaryPreamble?: string;
     force?: boolean;
     packages?: string[];
     filesPath?: string;
@@ -56,12 +57,14 @@ export function renderTex(
     content = opts.contentOrPath;
   }
   const { options, parts, doc } = template.prepare(opts);
+  let importsContent = renderImports(opts.imports, opts.packages);
+  importsContent += opts.glossaryPreamble ? '\n' + opts.glossaryPreamble : '';
   const renderer: TexRenderer = {
     CONTENT: content,
     doc,
     parts,
     options,
-    IMPORTS: renderImports(opts.imports, opts?.packages),
+    IMPORTS: importsContent,
   };
   const env = getDefaultEnv(template);
   const rendered = env.render(TEMPLATE_FILENAME, renderer);