-
Notifications
You must be signed in to change notification settings - Fork 22
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #98 from siefkenj/pretext
Report unsupported macros by katex and expand user-define commands * Break Up LaTeX Source on Section Macros (#101) Break up a latex source by divisions (`\section` , `\subsection`, etc.) and turn those divisions into environments. E.g., `\section{foo}XXX\section{bar}YYY` becomes ``` \begin{_section}[foo]XXX\end{_section} \begin{_section}[bar]YYY\end{_section} ``` This is an intermediate step in the PreTeXt conversion. * [WIP] author-info (#100) Add function to extract information from the `\author{...}` tag that appears before `\begin{document}...` * Fix the skipped test cases in the PreTeXt package (#103) Necessary macro subs and environment subs to create valid PreTeXt from LaTeX. * Added LaTeX to PreTeXt Plugin to the CLI package (#113) * started adding pretext package to cli * Upgrade deps * Rebuild documentation --------- Co-authored-by: Renee <[email protected]> Co-authored-by: Bo-Y-G <[email protected]>
- Loading branch information
Showing
51 changed files
with
4,272 additions
and
1,112 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,229 @@ | ||
| <!-- 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 | ||
| PluginOptions | ||
| ``` | ||
|
|
||
| ### Type | ||
|
|
||
| `Plugin<PluginOptions[], Ast.Root, Xast.Root>` | ||
|
|
||
| ```typescript | ||
| function unifiedLatexToPretext( | ||
| options: PluginOptions | ||
| ): (tree: Ast.Root, file: VFile) => Xast.Root; | ||
| ``` | ||
|
|
||
| ## `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` | | ||
|
|
||
| ## `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 & { | ||
| /** | ||
| * A boolean where if it's true then the output won't be wrapped in the <pretext><article> ... etc. tags. | ||
| * If it's false (default), a valid and complete PreTeXt document is returned. | ||
| */ | ||
| producePretextFragment?: boolean; | ||
| }; | ||
| ``` |
Oops, something went wrong.