Asciidoctor 数学

图书馆通过访问解析文档中的每个STEM节点并将其转换为图像，有效地用图像节点替换STEM节点来工作。这将转换STEM表达式的负担从转换器上移除。所有转换器看到的都是引用生成的图像的图像节点。

访问每个STEM节点时，扩展首先提取表达式的源代码。如果表达式是用AsciiMath编写的，扩展会使用AsciiMath库将表达式转换为LaTeX。然后，扩展将表达式传递给Mathematical，以将其渲染为图像。图像会自动调整大小以适应渲染后的表达式，并在必要时调整大小以适应行内。一旦生成了图像，扩展就会用引用生成的图像的图像节点替换文档中解析后的STEM节点。

当扩展处理完所有STEM节点后，它会取消文档上的`stem`属性，以表明不应对文档进行进一步的STEM处理。

由于Asciidoctor Mathematical将所有STEM节点替换为图像节点，它可作为STEM处理的通用解决方案。所有的转换器都知道如何处理图像节点。这个扩展既可以用于内置的转换器，也可以用于附加的转换器，如PDF和EPUB3。

Asciidoctor Mathematical与MathJax相比的主要缺点是，你无法对它生成的图像的大小和分辨率进行很多控制。它也缺乏MathJax所提供的与表达式的交互性。所以当你转换成HTML时，MathJax会给你一个更好的结果。

与MathJax相比的另一个缺点是它需要安装额外的库，而且这个库可能安装起来相当困难。尽管如此，如果你需要它并且愿意接受挑战，那就是我们接下来要去的方向。

Asciidoctor Mathematical作为一个名为https://rubygems.org/gems/asciidoctor-mathematical[asciidoctor-mathematical^]的gem分发。您可以使用Ruby包管理工具（gem或bundle）来安装它。

$ gem install asciidoctor-mathematical

然而，在安装这个gem时，你可能会遇到困难。Asciidoctor Mathematical依赖于Mathematical，后者是一个本地gem。换句话说，Mathematical需要在安装过程中重新编译，这需要能够访问主机系统上的构建工具和本地开发库。 目前，这个编译只适用于Linux系统。您不能在Windows上安装这个宝石。请参考Asciidoctor Mathematical文档中的安装部分 https://github.com/asciidoctor/asciidoctor-mathematical/#installation，以了解安装它所需的系统工具和开发库。

如果您在安装这个gem时遇到问题，或者需要在Windows上使用它，请考虑使用https://github.com/asciidoctor/docker-asciidoctor[Asciidoctor Docker容器]。 Asciidoctor Docker容器启动时预先安装了asciidoctor-mathematical gem。

一旦安装了Asciidoctor Mathematical，你可以在调用Asciidoctor时使用`-r`标志来激活该扩展。

$ asciidoctor -r asciidoctor-mathematical stem-sample.adoc

如果你通过API调用Asciidoctor，必须在调用Asciidoctor之前引入gem：

当扩展被激活时，它将自动在解析的文档中找到STEM节点，并将它们替换为图片。

为了获得最佳的输出质量和最大化转换速度，你应该配置Asciidoctor Mathematical来生成SVG文件。你可以使用`mathematical-format` AsciiDoc属性如下控制这个设置：

$ asciidoctor -r asciidoctor-mathematical -a mathematical-format=svg stem-sample.adoc

扩展程序现在将生成SVG图像而不是PNG图像。

要了解更多关于如何使用这个扩展以及它提供的选项的信息，请参阅https://github.com/asciidoctor/asciidoctor-mathematical项目的README文件。