JTEX

JTEX是一个用于从jinja-style模板渲染LaTeX文档的命令行工具（CLI）。该软件包使用修改后的环境和语法与LaTeX的标记良好兼容的Jinja2作为模板引擎。

这使得您可以从内容、数据和模板构建LaTeX文档。我们在开发针对Curvenote的基于模板的PDF/LaTeX导出系统时构建了此软件包，其中它用于从Curvenote社区模板存储库中的模板创建文档。

更改日志可在以下位置找到.

安装

使用pip将软件包安装到您的虚拟环境中

  pip install jtex

并输入以下命令以确认正确安装：

  jtex --version

示例

由于我们处理内容和数据，因此cli接受特定文件或文件夹的路径，而不是接受内联参数。以下是一个最小示例

给定以下2个文件

% content.tex
% ---
% title: Exploring Outer Space
% author:
%   name: Ana Space
%   email: ana@outer.space
% ---
Outer space is the expanse that exists beyond Earth and between celestial bodies. Outer space is not completely empty—it is a hard vacuum containing a low density of particles, predominantly a plasma of hydrogen and helium, as well as electromagnetic radiation, magnetic fields, neutrinos, dust, and cosmic rays.

content.tex包含一个front matter部分（由% ---分隔的标题注释块）以及内容本身。前部分包含一个格式为yaml的数据结构，该结构在模板渲染命名空间中可用，因此每个顶级键在全局范围内都是一个变量，如下面的template.tex所示。

% template.tex
\documentclass{article}

\title{[-title-]}
\author{[-author.name-] ([-author.email-])}

\begin{document}
\maketitle

[-CONTENT-]
\vskip 1cm
The End!
\end{document}

我们可以使用以下命令来渲染LaTeX文档：

  jtex freeform output.tex data.yml content.tex template.tex

以下内容将生成一个.tex文件：

% output.tex
% ---
% title: Exploring Outer Space
% author:
%   name: Ana Space
%   email: ana@outer.space
% ---
\documentclass{article}

\title{Exploring Outer Space}
\author{Ana Space (ana@outer.space)}

\begin{document}
\maketitle

% content.tex
Outer space is the expanse that exists beyond Earth and between celestial bodies. Outer space is not completely empty—it is a hard vacuum containing a low density of particles, predominantly a plasma of hydrogen and helium, as well as electromagnetic radiation, magnetic fields, neutrinos, dust, and cosmic rays.
\vskip 1cm
The End!
\end{document}

编译后生成以下文档：

文档布局灵活，将基于template.tex文件中的结构，其中使用修改后的jinja语法（[-，-]）来从data.yml中提供的匹配的DocModel中展开变量。

[-CONTENT-]是一个特殊变量，它将展开为content.tex的整个内容（）

此示例仅显示了变量展开（[-myvar-]），但完整的jinja2环境可用，包括控制流、过滤器以及许多Python命令。

上面显示的freeform命令没有偏见，可以用来渲染任何具有匹配DocModel数据结构的模板。

命令行界面概述

使用--help选项在任何时候都可以从命令行工具中获取帮助。

  jtex --help

注意：CLI使用typer，它提供了标准的shell完成选项。这些选项列在帮助消息中，建议安装，但这些命令不是使用此工具的核心。

命令概述

以下命令在CLI中可用。

freeform

freeform是一个无偏见的渲染命令，如上述示例所示，将允许您渲染任何给定的内容和DocModel的模板。

jtex freeform --help

Usage: jtex freeform [OPTIONS] TEMPLATE_TEX [CONTENT_TEX]

  Build a LaTeX document based on a free-form template, accompanying data
  structure and optional 'body' content. This can be used for general template
  rendering independently from Curvenote's prescriptive template structure. To
  build based on (and to develop/test) Curvenote templates use `build`.

Arguments:
  TEMPLATE_TEX   Path to a file with a compatible LaTeX template e.g.
                 mytemplate.tex. The template should align with the data
                 structure given by the DocModel  [required]
  CONTENT_TEX   Path to a file containing the content to render and jtex front
                matter.  [required]

Options:
  --output-tex FILE  Optional name of a local file to write the rendered
                     content to.This will override the data specified in the
                     front matter in content.
  --bib FILE         Path to an optional bib file. This will be copied as-is
                     into the target folder.
  --help             Show this message and exit.

在这个例子中，“DocModel”有点夸张，因为它只是定义在上述data.yml文件中的自由形式Python字典。

在构建模板时，您可以决定此文件中数据的结构，并使其与模板内访问的变量保持一致。要了解更多信息，请参阅创建模板

render

render是一个有偏见的渲染命令，旨在与Curvenote的内容和模板一起使用。

jtex render --help

Usage: jtex render [OPTIONS] CONTENT_FILE

  Build a LaTeX document based on a Curvenote LaTeX Template, accompanying
  docmodel data structure and content. Can be used to develop/test Curvenote
  templates.

Arguments:
  CONTENT_FILE  Path to a .tex file with containing jtex front matter content
                to render.  [required]

Options:
  --output-path DIRECTORY    If supplied with override the jtex.output.path
                             (and default path) specified in front matterThis
                             is useful when dynamically setting a temporary
                             output folder.Will be created if it does not
                             exist.
  --template-path DIRECTORY  If supplied with override the jtex.template
                             option and use the template found on this path
  --help                     Show this message and exit.

当从Curvenote的API导出LaTeX时，默认包含自定义环境和命令。这些需要在最终文档中加载特定包并包含定义。render将包括这些定义文件，并在渲染时期望DocModel中存在某些结构。

由于render通常不适用于Curvenote模板之外，我们在此不进一步讨论其细节。有关更多信息，请查看Curvenote Open Template Repo。

注意：Curvenote API还可以响应纯LaTeX，但渲染默认不是这种情况。有关通过编程访问Curvenote API的更多信息，请参阅Curvenote Python客户端。

validate

validate是一个测试运行命令，它将验证Curvenote模板。目前这是一种非常简单的验证，我们预计这将得到扩展。

jtex validate --help

Usage: jtex validate [OPTIONS] TEMPLATE_PATH

Arguments:
  TEMPLATE_PATH  Local folder containing the Curvenote compatible template to
                 validate  [required]

创建模板

此CLI工具使用定制的jinja2环境。我们将在下面解释自定义语法，以及如何结合使用content.tex和data.yml文件，比在前面的示例中显示的更详细。

然而，为了充分利用此工具，了解jinja的工作方式以及它提供的功能将非常有帮助。《Jinja模板设计者文档》是一个很好的资源，涵盖了jinja2语言在HTML渲染和标准jinja2语法中的所有功能。

该指南以及以下关于LaTeX渲染和我们的自定义语法的说明应提供您需要了解以创建自己的模板所需的所有信息。

Jinja

关于jinja模板

模板包含变量和/或表达式，在渲染模板时用值替换；以及标签，它们控制模板的逻辑。模板语法深受Django和Python的影响。

该命令行界面使用了一个经过以下修改的 jinja2 环境。

语法

以下是一个最小化的 LaTeX 示例，说明了这些修改：

\documentclass{article}
\begin{document}
\section{Famous People}
%% Print a list of famous people defined in the context dictionary
\begin{itemize}
[# for person in famous_people #]
\item [-person.name-], [-person.job-] [# if person.email #]([-person.email-])[# endif #]
[# endfor #]
\end{itemize}
\end{document}

这将打印出著名人士的名字、工作和（如果有）电子邮件地址。

其他环境差异

除了自定义语法之外，我们还设置了以下选项

jinja 在全局范围内提供了一系列 函数、测试 和 过滤器。我们通过添加 Python 的 __builtins__ 进一步扩展了这一功能，在 jinja 渲染环境中提供了额外的 常用 Python 函数。

构建 DocModel

我们使用“DocModel”一词来指代传递给 jinja 模板进行渲染的数据字典，该字典从内容文件中的“front matter”加载。jinja 文档称此为“上下文字典”。这很容易与您需要为使用 CLI 而创建的 yaml 相关联。

结构根级别的字段作为全局作用域中的变量在 jinja 上下文中可用。

# data.yml
title: Outer Space
author: Ana Cosmo

% template.tex
...
\title{[-title-]}
\author{[-author-]}
...

您可以在模板中添加注释，这些注释将在渲染时被删除。万一带错，这些注释也是有效的 LaTeX 注释，因此即使有注释泄漏，也不会影响您的构建

  % template.tex

  % this is a LaTeX comment
  %# this is a template comment and will be removed at render, but it is also a valid LaTeX comment #%

这些变量本身可以是字典、列表、字符串、数字和布尔值的嵌套数据结构

# data.yml
authors:
  - name: Ana Cosmo
    email: ana@thecosmos.org
  - name: Bill Saturn
    email: bill@gasgiant.com
tags:
  - space
  - planets
  - cosmos

% template.tex
...
[# for author in authors #]
\author{[-author.name-] ([-author.email-])}
[# endfor #]

The first author is [-authors[0].name-]
The last author is [-authors[-1].name-]

tags: [-tags|join(', ')-]

%# main content goes here #%
[-CONTENT-]
...

[-CONTENT-] 是一个特殊变量，它将扩展到 content.tex 的全部内容

我们不会在这里详细介绍更多的 jinja 功能，因为它们已在 Jinja 模板设计者文档 中介绍。只需将标准的 jinja 语法替换为我们的自定义 语法，并牢记 LaTeX 和构建复杂模板的规则，经过实践会变得相当简单。

Curvenote 模板

要查看我们在 Curvenote 开发的模板，或获取如何为 Curvenote 创建模板的文档，请访问 开源模板仓库 并查看那里的文档。

我们使用此 CLI 工具进行开发、测试和验证提交给该仓库的任何模板。