> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/zh-cn/shen-ru-wen-zhang/36-pandora-s-hbox-using-luatex-to-lift-the-lid-of-tex-boxes.md).

# 潘多拉的 \hbox：使用 LuaTeX 揭开 TeX 盒子的盖子

## 引言

盒子和胶水是两个关键概念，为 TeX 的排版模型和功能奠定了基础。在上一篇文章的入门内容基础上， [盒子与胶水：使用 LuaTeX 的简短但可视化的介绍](/latex/zh-cn/shen-ru-wen-zhang/11-boxes-and-glue-a-brief-but-visual-introduction-using-luatex.md)，这篇配有大量插图的文章将更详细地探讨盒子和胶水。我们还推出了一个基于 LuaTeX 的新 [Overleaf 项目](https://www.overleaf.com/latex/examples/exploring-the-structure-of-tex-boxes-with-luatex/pwdrypmtdbgs) ，它使你能够探索 TeX 盒子的深层内部结构——从而帮助你真正理解其行为。该 Overleaf 项目的创建在很大程度上得益于 Patrick Gundlach 的工作，因此我们向他表示 [感谢](#credits-thanks-patrick).

## 为什么选择 LuaTeX？

首先，值得再次说明 LuaTeX 和 LuaLaTeX 之间的区别：

* LuaTeX 是一个基于 TeX 的排版引擎可执行程序的名称；
* LuaLaTeX 指的是将 LaTeX 宏包与 LuaTeX 引擎结合使用。

这一区别极其重要，因为本文利用的是 LuaTeX 引擎本身的内置功能，而不仅仅是使用 LaTeX 宏包所提供命令的特性和功能。

不确定 TeX 引擎与 LaTeX 宏包之间区别的读者，可能希望阅读我们此前发表的一篇文章， [《名称里有什么：TeX 的多种风格指南》](/latex/zh-cn/shen-ru-wen-zhang/55-what-s-in-a-name-a-guide-to-the-many-flavours-of-tex.md)，其中对这些区别作了较详细的说明。同一篇文章还讨论了作为编程语言的“TeX”，以及基于 TeX 的排版引擎（例如 pdfTeX、XeTeX 和 LuaTeX）不仅在特性和功能上各不相同，所支持的 TeX 语言“风格”也存在差异。这就引出了我们选择 LuaTeX 的原因。LuaTeX 除了支持一种基于 TeX 的编程语言外，还嵌入了 Lua 脚本语言——提供了一种简单却非常强大的常规编程语言。借助 Lua 和 LuaTeX 的内置功能，你能够以其他任何 TeX 引擎无法提供的方式探索和控制 LuaTeX 的排版活动——其中包括探查 TeX 盒子的内部结构；因此，LuaTeX 是本文及配套 Overleaf 项目的理想（也是唯一）选择。

### pdfTeX/XeTeX 与 LuaTeX：图解

以下 *示意图* 旨在突出显示 pdfTeX/XeTeX 与 LuaTeX 设计之间的一项重要对比。当然，pdfTeX 和 XeTeX 都允许用户编写能够影响排版行为的 TeX 代码；不过，这些 TeX 引擎所包含的更深层内部结构，以及在排版过程中构建的底层数据，大多无法通过用户命令和宏访问。从这个意义上说，与 LuaTeX 相比，它们是 *相对* 封闭的系统。

#### pdfTeX/XeTeX

![{{{alt}}}](/files/1f5d97cf732ed3952fb3dab11bc676e36d6e4f93)

#### LuaTeX

LuaTeX 引入了一个名为 `\directlua{...}` 的新原始命令，通过它，你不仅可以完全访问 Lua 语言，还能够使用 C 和 C++ 等语言编写插件来扩展 LuaTeX 的功能。在 Windows 上，此类插件称为 *动态链接库* （.DLL）；在 Linux 上，它们称为 *共享对象库* （.so）。不过，LuaTeX 的真正强大之处源于其庞大的内置 Lua 函数集，它们提供对 LuaTeX 内部机制的访问——从而能够对基于 TeX 的排版进行极其复杂的控制和编程。这类函数的集合称为 API（应用程序编程接口），通过 LuaTeX 的 API，你可以使用 Lua 程序与其基于 TeX 的排版引擎和数据结构通信。

![{{{alt}}}](/files/2be0df2045335d899dba26eb13f1af044f14be1a)

使用 LuaTeX 的 `\directlua{...}` 命令，例如，你可以访问其他 TeX 引擎中隐藏的底层内部 TeX 数据结构。此外，你还可以使用 Lua 脚本进行各种编程计算、字符串操作等，并将结果传回 TeX：可能性几乎无穷无尽。不过，本文并非旨在详细阐述或教程式介绍 LuaTeX——尽管人们很容易想给出一些能展示这款强大得惊人的 TeX 引擎极高灵活性的示例。

## 盒子和胶水：简要回顾

如文章中所介绍， [盒子与胶水：使用 LuaTeX 的简短但可视化的介绍](https://www.overleaf.com/blog/511-boxes-and-glue-a-brief-but-visual-introduction-using-luatex) 盒子和胶水是支撑 TeX 排版功能的两个关键概念。下图非常简要地帮助回顾 TeX 水平盒子和垂直盒子类型的行为。请注意：水平盒子当然可以包含以从右到左语言（例如阿拉伯语或希伯来语）排版的文本，这意味着盒子的增长方向可能与下图中水平盒子所示的方向相反。

![{{{alt}}}](/files/46295aa5880ab381c862783d8b7648ac68ea29dc)

### 用于构建盒子的 TeX 原始命令

如今，大多数人使用 LaTeX 宏包来编写 TeX 文档；它旨在提供命令，使用户不必直接面对大量 TeX 底层语言——即所谓的 *原始命令*——内置于 TeX 引擎的核心命令（参见文章 [《名称里有什么：TeX 的多种风格指南》](/latex/zh-cn/shen-ru-wen-zhang/55-what-s-in-a-name-a-guide-to-the-many-flavours-of-tex.md) ，了解对 TeX 原始命令的讨论）。LaTeX 宏集合提供了各种用于创建和存储（保存）盒子的宏，但如果剥去所有宏代码，就会发现仅有 4 个底层的原始盒子构建命令：

用于创建水平列表：

* \hbox{...}

用于创建和堆叠垂直列表：

* \vbox{...}
* \vtop{...}
* \vcenter{...}

我们不会解释如何使用所有这些盒子命令，因为网络上或 TeX/LaTeX 书籍中已有大量示例和教程——但我们会看看盒子在 TeX 数据结构内部是如何表示和存储的。

### 胶水：弹性间距

实际上，胶水是 TeX 用来在水平或垂直方向上对项目进行间隔和定位的一种间距形式。作为 TeX 用户，我们可以指示 TeX 插入固定大小的胶水，也可以使用弹性胶水——它可按我们的需求具有任意的伸展或收缩弹性。用于创建水平间距胶水的 TeX 命令之一称为 `\hskip` ，其形式为

`**\hskip** <自然宽度> **plus** <伸展量> **minus** <收缩量>`

`**plus**` 和 `**minus**` 是 TeX 关键字，但并非每个胶水都需要使用它们。如果 `**plus**` 或 `**minus**` 不存在，则相应的 `<伸展量>` 或 `<收缩量>` 假定为零。例如， `\hskip 3pt` 插入一个没有伸展或收缩部分的固定宽度胶水。

暂且将 `<伸展量>` 和 `<收缩量>` 视为我们对 *建议* ，因为精确的伸展或收缩量将由 TeX 计算。

为帮助理解这些概念，下图将胶水表示为弹簧。 `<自然宽度>` 是弹簧在没有拉力（伸展）或压力（收缩）时的长度。 `<伸展量>` 和 `<收缩量>` 相对于弹簧的自然长度显示。

![{{{alt}}}](/files/b07c88aa788da3f88bbbddbac4b0781a03b69638)

#### 一个 \hbox 示例

假设我们想创建一个 `\hbox{...}` ，其中仅包含字母 A、B、C 和 D，并且需要该盒子宽为 100pt（100 个 TeX 点）。此外，可以肯定这四个字符的总宽度远小于 100pt，这表明 TeX 需要某种方式填满盒子内的剩余空间：我们将使用一些胶水来完成。不过，由于我们不知道填满盒子所需胶水的确切量，最好添加一些弹性胶水，让 TeX 负责计算这些胶水需要占用的空间量。在下面的代码片段中，请注意使用“%”来抑制由行尾字符产生的词间空格。

```
\hbox to100pt{%
A\hskip4pt plus3pt minus 2pt B%
\hskip 0pt plus 2fil C%
\hskip 0pt plus 2fill D%
\hskip 0pt plus 3fill}
```

生成的盒子如下所示（为清晰起见已放大）：

![{{{alt}}}](/files/4b40306fa5b0f588df2ee2fcba69e8e5244273ee)

这 `\hbox` 上面叠加了虚线盒子（红色），以指示字符的宽度（按 TeX 所见）。出于排版目的，字符被视为小盒子，而填充此 `\hbox`所需的胶水量，是通过考虑每个字符的宽度来确定（计算）的。

结果表明，TeX 没有伸展或收缩 A 与 B 之间的胶水（设置为 4pt），而 B 与 C 之间没有胶水（设置为 0pt）。但是，C 与 D 之间的胶水，以及 D 与盒子末端之间的胶水都大幅伸展，因为这些胶水具有最灵活的伸展分量——实际上，这些胶水吸收了填满盒子所需的所有伸展量。

## 回到 LuaTeX

到目前为止，我们已经探索了盒子和胶水，并看到 LuaTeX 可以访问在 pdfTeX 和 XeTeX 中隐藏的内部 TeX 结构。现在该通过示例让这一点更明确了；但首先，我们需要简要了解 TeX 在内存中存储盒子的方式——我们将从一个类比开始。

### TeX 如何在内存中存储盒子：一个类比

假设出于某种原因，你需要创建一个描述实体盒子的数据模型。你会选择哪些数据来提供这种描述？一种可采取的方法是将信息分成两部分：关于实体盒子本身的数据，以及提供盒子内容列表的数据。因此，我们的简单模型可能如下所示：

1. 关于实体盒子的数据（“元数据”）：

* width
* 高度
* 深度
* 重量
* 颜色
* 类型（木制、塑料、纸板）

3. 关于盒子内容的数据：以某种形式的列表描述其包含的项目——可能不按任何特定顺序列出。

这与 TeX 存储盒子的方式有着非常密切的类比关系。

### TeX 如何在内存中存储盒子：hlists 和 vlists

在内部，TeX 创建称为 *hlists* （水平列表）和 *vlists* （垂直列表）的“容器”，它们分别表示 hbox 和 vbox。这些 hlist/vlist 对象提供了关于盒子的一组“元数据”，并可访问盒子实际包含的对象列表——该列表称为 *节点列表*。与可按任何顺序在实体盒子中放置物品不同，对 TeX 而言，盒子内容的顺序极为重要——它们是要被排版的项目。如果你有任何编程或计算机科学背景，得知 TeX 盒子中的对象采用所谓的 [双向链表](https://en.wikipedia.org/wiki/Doubly_linked_list)进行存储并保留其创建顺序，你不会感到惊讶。我们不会进一步讨论链表，因为网络上充满了教程、示例和解释。

节点和节点列表的概念是 TeX 工作方式的一个基本方面，但为了本文的目的，我们只作简要概述。节点本质上是一种“迷你容器”，而且（截至 LuaTeX 1.04）大约有 50 种不同类型的节点：反映了 LuaTeX 用于排版的内部数据类型和组件。例如，有用于表示以下对象的节点：字形（由“字符”产生）、胶水、水平/垂直规则、惩罚、“whatsit”、字距调整等。所有排版材料最终都会成为一个巨大节点列表的一部分，而 LuaTeX 让你可以直接访问这些内部数据结构。LuaTeX 还允许你添加、编辑、修改或创建节点列表，因此，例如，你可以直接在 Lua 代码中创建盒子，完全不必使用任何 TeX 代码。不过，这将留待日后再谈。

### \directlua{...} 实际运行的一个简单示例

以下示例创建一个 `\hbox` ，并将其保存到盒子寄存器 0 中。接着，我们使用传统 TeX 代码报告盒子的宽度，并通过 `\directlua{}`使用第二种方法获取相同信息。这里，我们运行一段小型 Lua 脚本，访问 TeX 的内部盒子存储区域以获得盒子的宽度——当然，两个值相同：2412092sp（sp=缩放点：65536sp = 1 个 TeX 点）。归根结底，在这个极其简单的示例中，TeX 代码和 Lua 代码都检查相同的内部数据结构以获取盒子的宽度；但正是通过这条直接访问路径，LuaTeX 打开了通往丰富信息和控制能力的大门，而这些能力在其他引擎中并不可用。

![{{{alt}}}](/files/5a1c04f8c8f899f5b31a11f14f951cddcdc8e6ed)

```latex
\documentclass{article}
\begin{document}
\setbox0=\hbox{A\hskip 5pt B\hskip 10pt C}
\fontsize{18}{22}\selectfont
\noindent 使用 \TeX{} 代码，盒子 0 的宽度为 \number\wd0\relax \space sp\par
\noindent 我们还可以使用 Lua，并调用 Lua\TeX 的一个函数来获取相同的
信息。\vskip10mm
\noindent 使用 Lua 代码，盒子 0 的宽度为
\directlua{
local boxwidth = tex.box[0].width
tex.print(boxwidth.." sp")
}，它当然与从 \TeX{} 代码获得的值相同。
\end{document}
```

## 综合起来：一个 Overleaf 项目

我们已经指出，在内部，TeX 将盒子表示为称作 hlists/vlists 的“容器”；它们存储盒子的“元数据”，并提供对构成盒子的组件列表的访问。使用 LuaTeX，你可以访问盒子的“元数据”及 TeX 盒子中包含的项目列表：字形、胶水、惩罚、其他盒子等等。使用 Lua 脚本，可以检查位于 TeX 内存中的盒子，并绘制出该盒子所含内容的详细表示。使用 *节点图* 可以实现对 TeX 盒子及其内容的恰当表示，而我们准备了一个 [Overleaf 项目](https://www.overleaf.com/latex/examples/exploring-the-structure-of-tex-boxes-with-luatex/pwdrypmtdbgs) ，它借助 Patrick Gundlach 编写的优秀 Lua 脚本（见致谢）来完成此事。我们不会描述检查盒子和生成节点图所需的详细过程——仅需指出，任何处理 TeX 盒子的程序/脚本都必须是 *递归* ，因为盒子可以嵌套：即，你可以在 vbox 内放置 hbox，再在 hbox 内放置……以极深层级嵌套组合所有盒子类型。

![{{{alt}}}](/files/ec1b29ba11b8fc8aa75adfd8337734c906c0b492)

### 该项目提供什么？

它只实现了一个名为 `\dobox{盒子命令}`的命令，例如：

```latex
\dobox{\hbox to100pt{%
A\hskip4pt plus3pt minus 2pt
B\hskip 0pt plus 2fil
C\hskip 0pt plus 2fill
D\hskip 0pt plus 3fill}}
```

该 `\dobox{...}` 命令执行多项任务：

1. 在文档中以原样排版方式输出盒子的 TeX 代码；
2. 它生成该 TeX 盒子的 SVG 图形——你可以将其嵌入网页中（正如我们在这篇博客文章中所做的）；
3. 它生成节点列表的 SVG 图形——你也可以将其嵌入网页中（正如我们在这篇博客文章中所做的）；
4. 它输出节点列表的 PDF 图形，然后将其导入由该项目生成的主 PDF 文档。

由于 LuaTeX 为表示复杂 TeX 盒子（例如当前正在构建的页面或排版的数学内容）需要存储海量数据，节点图很快会变得极其庞大。对于较大的节点列表，导入的 PDF 图形可能会被文档的页面边界裁剪——如果你想查看大型节点图，可以下载项目的 ZIP 文件并提取感兴趣的 PDF 图形。下载项目 ZIP 文件时，请务必从下拉选项列表中选择“输入和输出文件”：

![{{{alt}}}](/files/d1a50a8d19016f5b0b89aa1d8846f02c0d4126b3)

### Overleaf 项目生成的图形：简要说明

在展示一些示例之前，值得对 Overleaf 项目生成的图形作几点说明——我们将使用文章前面提到的同一个 `\hbox` 示例。以下是它封装在项目的 `\dobox{...}` 命令设置为特定值：

```latex
\dobox{\hbox to100pt{%
A\hskip4pt plus3pt minus 2pt
B\hskip 0pt plus 2fil
C\hskip 0pt plus 2fill
D\hskip 0pt plus 3fill}}
```

以下是由 TeX 生成的 `\hbox` ——为清晰起见，盒子已放大，但边框包含在 Overleaf 项目生成的图形中。

![{{{alt}}}](/files/618009dcee28321a9557714c72691a8b2b62060c)

以下是一个 *带注释的* SVG 图，显示表示上述盒子的节点列表——添加了注释以突出盒子的“元数据”及其包含的对象列表：这些注释并不出现在 Overleaf 项目生成的图形中。

[![{{{alt}}}](/files/eba9dc6dc44c13498bc2b3cabbca9fb91c1ac1a0)](https://www.filepicker.io/api/file/ZSwIylUR66eFYPMo0suX)

如果查看“元数据”部分，可能会注意到一些不熟悉的参数：

* `glue_set`
* `glue_sign`
* `glue_order`

这些参数是 TeX 用于计算该盒子内胶水需要伸展或收缩多少的设置，只是可通过 LuaTeX 轻松获取、却无法通过其他 TeX 引擎获取的数据示例之一。请注意，盒子组件中包含的胶水节点 *保留* 了我们为创建盒子而输入的原始胶水值。这一点至关重要，因为 TeX 提供命令 `\unhbox`, `\unvbox`, `\unhcopy`, `\unvcopy` ，它们会“拆箱”盒子的内容，并将其释放回输入流，以再次参与排版操作。只有当 TeX 最终将盒子输出（ship out）到 PDF 或 DVI 文件时， `glue_set`, `glue_sign` 和 `glue_order` 才会应用于盒子中包含的任何胶水——以计算在盒子内定位组件所需的实际伸展或收缩量，然后生成相应的 PDF 数据或 DVI 操作码。

“元数据”中列出的另一个参数是 `shift`：这是应用以下 TeX 命令所产生的盒子位移值：

* `\raise`, `\lower` （应用于一个 `\hbox`);
* `\moveleft`, `\moveright` （应用于一个 `\vbox`).

在我们的示例中， `shift` 为 0pt，因为我们没有将 `\hbox` 从其自然位置移开。

该 [Overleaf 项目](https://www.overleaf.com/latex/examples/exploring-the-structure-of-tex-boxes-with-luatex/pwdrypmtdbgs) 还会以 PDF 格式输出节点图：以下是下载一个 [PDF 文件版本](https://www.filepicker.io/api/file/bezigXESC2FSasvjoh8A) 的上述节点图的链接。

### Overleaf 项目如何创建这些图形？

Overleaf 项目利用了运行安装在 Overleaf 服务器上的软件工具和实用程序的能力——参见 [这篇博客文章](/latex/zh-cn/shen-ru-wen-zhang/52-using-luatex-to-run-tools-and-utilities-installed-on-overleaf-s-servers.md) 以了解更多细节和一个示例项目。为生成表示 TeX 盒子的 SVG 图形，盒子的 TeX 代码被写入一个小文件，随后使用 pdfTeX 对其排版以生成 DVI 文件——请注意，pdfTeX 程序由 LuaTeX 通过几行 Lua 脚本执行。该 DVI 文件使用 `dvisvgm` 实用程序即时转换为 SVG——该实用程序随安装在 Overleaf 服务器上的 TeX Live 发行版提供。 `dvisvgm` 使用命令行选项执行 `-n` ，以确保任何排版文本都转换为直线/曲线，从而使 SVG 文件的正确渲染不依赖于安装 TeX 字体。

为创建节点图，我们使用一个名为 `hiviznodelist.lua` 的 Lua 脚本，它基于 Patrick Gundlach 的工作。该脚本写出一个所谓的 `.gv` （Graphviz）文件；它是一个文本文件，包含使用 `dot` 语言描述的节点图。该 `.gv` 文件由一个名为 `dot` 的实用程序处理，该程序以 PDF 和 SVG 两种文件格式输出节点图。

### 项目示例

以下是使用 Overleaf 项目生成 SVG 图形的一些附加示例。包含大量文本（例如在 \vbox 中）或复杂数学内容的盒子会生成巨大的节点图——如果你探索该 Overleaf 项目，建议不要使用不必要地复杂的盒子来展示你感兴趣的功能。

#### \vbox to 25pt{A}

本示例展示了将文本直接放入一个 `\vbox`的效果：请注意，即使是这样一个简单的盒子，节点结构也相当复杂。这种复杂性的原因是，直接放入一个 `\vbox` 的文本会导致 TeX 执行断行。你可以看到该 `\vbox` 宽度为 345pt：即 `\hsize` 在创建此盒子时的值。还请注意，字符“A”包含在一个 `hlist` 中，它的宽度也是 345 点；并注意盒子内容末尾的大惩罚值（10000）以及 `\parfillskip` 和 `\rightskip` 胶水。这一惩罚和两个胶水项目由 TeX 的断行活动插入。如果查看段落行（ `glue_set` ）的`hlist`值，该行包含字母“A”，你会发现它极大（322.500000）：为什么？这是因为段落行宽 345pt，却只包含一个 `\parindent` 和字母“A”：剩余空间必须由 `\parfillskip` 胶水填充，而它必须伸展相当大的距离才能填满该行的剩余空间。

![{{{alt}}}](/files/dadb4939c4ba1115ce81154fd1dc6fd49ca12fb6)

[![{{{alt}}}](/files/f4f3a52d5ee2f41d9640303efcb5913106df1a16)](https://www.filepicker.io/api/file/pVtHsNGSQ4m09vBZuOpQ)

[下载 PDF 文件](https://www.filepicker.io/api/file/nBS0uDs2QjqKCKljAm7r)

#### \vbox to 25pt{\hbox{A}}

将此示例与前一个进行比较很有启发性。这里不仅节点图小得多，而且该 `\vbox` 的宽度仅为 7.50002pt：与字符“A”的宽度相同。原因是“A”被包裹在一个 `\hbox` 中，这会阻止 `\vbox` 触发 TeX 执行断行——这是使用 `\vbox`.

![{{{alt}}}](/files/c88d802720e615c30376b5e9f4935a19fd842719)

[![{{{alt}}}](/files/84bb1494a143d73f395e00f5dd1a80e3513db25b)](https://www.filepicker.io/api/file/LHepknjnRGOVEdghW4qH)

[下载 PDF 文件](https://www.filepicker.io/api/file/Yk3uCCQR5ao8Yd3TJCdE)

#### 简单数学：\hbox{$$\displaystyle \int f(x) dx$$}，复杂盒子！

本示例表明，即使非常简单的排版数学内容也会创建详细的盒子结构：数学排版会产生 *极其* TeX 内部的复杂数据结构！

![{{{alt}}}](/files/fd785b085b8b7a24de5bd263adc74c16680b3e94)

[![{{{alt}}}](/files/4f4f7dc4b4094f43f109f0f0781c75a882ab828f)](https://www.filepicker.io/api/file/oVFNNvCqT0eZP0qS2odk)

[下载 PDF 文件](https://www.filepicker.io/api/file/D5TepsdaSdeYZvkuSEJt)

## 致谢：谢谢你，Patrick！

我们感谢 [Patrick Gundlach](https://twitter.com/patrickgundlach) ，他已授权 Overleaf 使用和分发其 Lua 脚本的修改版本， `viznodelist.lua`，该脚本处理 TeX 盒子并输出一个文件（采用 `dot` 语言），可对其进行处理以绘制节点图。Overleaf 项目包含一个名为 `hiviznodelist.lua`的 Lua 脚本——这是 Patrick 原始代码的重命名和修改版本，其原始代码可在 [Github](http://gist.github.com/556247)上获取。Patrick 创建了一个名为 [speedata Publisher](https://speedata.github.io/publisher/index.html) 的开源 LuaTeX 排版系统，你可以免费下载和使用——也提供商业支持选项。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/latex/zh-cn/shen-ru-wen-zhang/36-pandora-s-hbox-using-luatex-to-lift-the-lid-of-tex-boxes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.