Merge remote-tracking branch 'upstream/pretext'

packages/unified-latex-lint/README.md

@@ -26,4 +26,4 @@ import the `.js` file. To explicitly access the commonjs export, import the `.cj
 
 | Name    | Type                                                                                                                                                                                                                  | Description                           |
 | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |
-| `lints` | `{ unifiedLatexLintArgumentColorCommands: Plugin<void[] \| [{ fix?: boolean; } \| [boolean \| Label \| Severity, { fix?: boolean; }?]], Root, Root>; ... 7 more ...; unifiedLatexLintPreferSetlength: Plugin<...>; }` | Object exporting all available lints. |
+| `lints` | `{ unifiedLatexLintArgumentColorCommands: Plugin<void[] \| [{ fix?: boolean; } \| [boolean \| Severity \| Label, { fix?: boolean; }?]], Root, Root>; ... 7 more ...; unifiedLatexLintPreferSetlength: Plugin<...>; }` | Object exporting all available lints. |

packages/unified-latex-to-pretext/README.md

@@ -0,0 +1,257 @@
+<!-- DO NOT MODIFY -->
+<!-- This file was autogenerated by build-docs.ts -->
+<!-- Edit the docstring in index.ts and regenerate -->
+<!-- rather than editing this file directly. -->
+# unified-latex-to-pretext
+
+## What is this?
+
+Functions to convert `unified-latex` Abstract Syntax Tree (AST) to a XAST (xml-like)
+tree in the [PreTeXt](https://pretextbook.org/) format.
+
+## When should I use this?
+
+If you want to convert LaTeX to PreTeXt for further processing with the PreTeXt compiler.
+
+## Controlling the PreTeXt output
+
+This plugin comes with presets for several common LaTeX macros/environments, but you probably want to
+control how various macros evaluate yourself. For example, you may have used `\includegraphics` with `pdf`s
+in your LaTeX source by want the output to reference different files.
+You can accomplish this by passing `macroReplacements` (for environments, there is the similarly-named
+`environmentReplacements`) to the plugin.
+
+For example,
+
+```typescript
+import { unified } from "unified";
+import rehypeStringify from "rehype-stringify";
+import { htmlLike } from "@unified-latex/unified-latex-util-html-like";
+import { printRaw } from "@unified-latex/unified-latex-util-print-raw";
+import { unifiedLatexToPretext } from "@unified-latex/unified-latex-to-pretext";
+import { unifiedLatexFromString } from "@unified-latex/unified-latex-util-parse";
+import { getArgsContent } from "@unified-latex/unified-latex-util-arguments";
+
+const convert = (value) =>
+    unified()
+        .use(unifiedLatexFromString)
+        .use(unifiedLatexToPretext, {
+            macroReplacements: {
+                includegraphics: (node) => {
+                    const args = getArgsContent(node);
+                    const path = printRaw(
+                        args[args.length - 1] || []
+                    ).replace(/\.pdf$/, ".png");
+                    return htmlLike({
+                        tag: "img",
+                        attributes: { src: path },
+                    });
+                },
+            },
+        })
+        .use(rehypeStringify)
+        .processSync(value).value;
+
+console.log(convert(`\\includegraphics{foo.pdf}`));
+```
+
+`macroReplacements` and `environmentReplacements` functions can return any unified-latex `Node`, but
+using the `htmlLike` utility function will return nodes that get converted to specific HTML. See `htmlLike`'s
+documentation for more details.
+
+## Install
+
+```bash
+npm install @unified-latex/unified-latex-to-pretext
+```
+
+This package contains both esm and commonjs exports. To explicitly access the esm export,
+import the `.js` file. To explicitly access the commonjs export, import the `.cjs` file.
+
+# Plugins
+
+## `unifiedLatexToPretext`
+
+Unified plugin to convert a `unified-latex` AST into a `xast` AST representation of PreTeXt source.
+
+### Usage
+
+`unified().use(unifiedLatexToPretext[, options])`
+
+#### options
+
+```typescript
+HtmlLikePluginOptions
+```
+
+### Type
+
+`Plugin<HtmlLikePluginOptions[], Ast.Root, Xast.Root>`
+
+```typescript
+function unifiedLatexToPretext(
+  options: HtmlLikePluginOptions
+): (tree: Ast.Root, file: VFile) => Xast.Root;
+```
+
+where
+
+```typescript
+type HtmlLikePluginOptions = {
+  /**
+   * Functions called to replace environments during processing. Key values should match environment names.
+   *  You probably want to use the function `htmlLike(...)` to return a node that gets converted to specific HTML.
+   */
+  environmentReplacements?: EnvironmentReplacements;
+  /**
+   * Functions called to replace macros during processing. Key values should match macro names.
+   * You probably want to use the function `htmlLike(...)` to return a node that gets converted to specific HTML.
+   */
+  macroReplacements?: MacroReplacements;
+};
+```
+
+## `unifiedLatexWrapPars`
+
+Unified plugin to wrap paragraphs in `\html-tag:p{...}` macros.
+Because `-` and `:` cannot occur in regular macros, there is no risk of
+a conflict.
+
+### Usage
+
+`unified().use(unifiedLatexWrapPars[, options])`
+
+#### options
+
+```typescript
+PluginOptions
+```
+
+### Type
+
+`Plugin<PluginOptions[], Ast.Root, Ast.Root>`
+
+```typescript
+function unifiedLatexWrapPars(options: PluginOptions): (tree: Ast.Root) => void;
+```
+
+## `xmlCompilePlugin`
+
+Unified plugin to convert a `XAST` AST to a string.
+
+### Usage
+
+`unified().use(xmlCompilePlugin)`
+
+### Type
+
+`Plugin<void[], Root, string>`
+
+```typescript
+function xmlCompilePlugin(): void;
+```
+
+# Functions
+
+## `attachNeededRenderInfo(ast)`
+
+Attach `renderInfo` needed for converting some macros into their
+katex equivalents.
+
+```typescript
+function attachNeededRenderInfo(ast: Ast.Ast): void;
+```
+
+**Parameters**
+
+| Param | Type      |
+| :---- | :-------- |
+| ast   | `Ast.Ast` |
+
+## `convertToPretext(tree, options)`
+
+Convert the `unified-latex` AST `tree` into an HTML string. If you need
+more precise control or further processing, consider using `unified`
+directly with the `unifiedLatexToPretext` plugin.
+
+For example,
+
+    unified()
+         .use(unifiedLatexFromString)
+         .use(unifiedLatexToPretext)
+         .use(rehypeStringify)
+         .processSync("\\LaTeX to convert")
+
+```typescript
+function convertToPretext(
+  tree: Ast.Node | Ast.Node[],
+  options: PluginOptions
+): string;
+```
+
+**Parameters**
+
+| Param   | Type                     |
+| :------ | :----------------------- |
+| tree    | `Ast.Node \| Ast.Node[]` |
+| options | `PluginOptions`          |
+
+where
+
+```typescript
+type PluginOptions = {
+  /**
+   * Functions called to replace environments during processing. Key values should match environment names.
+   *  You probably want to use the function `htmlLike(...)` to return a node that gets converted to specific HTML.
+   */
+  environmentReplacements?: EnvironmentReplacements;
+  /**
+   * Functions called to replace macros during processing. Key values should match macro names.
+   * You probably want to use the function `htmlLike(...)` to return a node that gets converted to specific HTML.
+   */
+  macroReplacements?: MacroReplacements;
+};
+```
+
+## `wrapPars(nodes, options)`
+
+Wrap paragraphs in `<p>...</p>` tags.
+
+Paragraphs are inserted at
+
+*   parbreak tokens
+*   macros listed in `macrosThatBreakPars`
+*   environments not listed in `environmentsThatDontBreakPars`
+
+```typescript
+function wrapPars(
+  nodes: Ast.Node[],
+  options: {
+    macrosThatBreakPars?: string[];
+    environmentsThatDontBreakPars?: string[];
+  }
+): Ast.Node[];
+```
+
+**Parameters**
+
+| Param   | Type                              |
+| :------ | :-------------------------------- |
+| nodes   | `Ast.Node[]`                      |
+| options | <span color='gray'>Omitted</span> |
+
+# Constants
+
+| Name                                   | Type                                                                |
+| :------------------------------------- | :------------------------------------------------------------------ |
+| `KATEX_SUPPORT`                        | `{ macros: any; environments: any; }`                               |
+| `katexSpecificEnvironmentReplacements` | `Record<string, (node: Ast.Environment) => Ast.Node \| Ast.Node[]>` |
+| `katexSpecificMacroReplacements`       | `Record<string, (node: Ast.Macro) => Ast.Node \| Ast.Node[]>`       |
+
+# Types
+
+## `PluginOptions`
+
+```typescript
+export type PluginOptions = HtmlLikePluginOptions & {};
+```