☰

使用l3doc编写LaTeX文档时的索引问题

tag-icon • tag-icon indexing latex3 documentation
使用l3doc编写LaTeX文档时的索引问题

我过去常常l3doc为我的包写文档。在文档中我需要描述包的宏、环境和选项。我开始function只使用环境。在@egreg（谢谢！）给出提示后，我找到了环境environment。由于我找不到文档l3doc。我遇到了更多问题。这是一个例子：

\documentclass{l3doc}
\usepackage{lipsum} % to generate some text

\begin{document}

\lipsum

\begin{function}{\macro}
this is a macro.
\end{function}

\begin{environment}{env}
this is an env.
\end{environment}

\begin{function}{opt}
\begin{syntax}
    opt = \meta{a}
\end{syntax}
this is an opt.
\end{function}

\PrintIndex

\end{document}

我使用下面的命令来编译它：

pdflatex example
makeindex -s l3doc.ist example
pdflatex example
pdflatex example

结果如下： 结果

存在几个问题：

  1. 您可以看到该条目env重复了两次。
  2. 条目的页码env错误。
  3. 该条目应在而不是opt下进行索引。由于它是一个选项而不是环境，因此我无法使用。我需要。OPenvironmentsyntax

谢谢你的帮助。

答案1

问题在于，这l3doc实际上在某种程度上是项目内部的问题，而不是我们认为的稳定或正确记录的问题——简而言之，它是一堆用于文档的黑客和附加组件，我们对其进行了试验并发现它们对我们自己的东西很有用，但从未完成并为其编写适当的文档。

您可以通过排版找到那里的文档，l3doc.dtx但您就会明白我的意思：用户界面中并非记录了所有内容，代码大部分没有注释或附加信息。尽管如此，它可能会为您提供一些额外的信息，但请注意，我们可能会更改或添加这些界面。

至于您上面的问题：l3doc.ist在将 levelchar 设置为 时出现/存在错误，#但是代码仍然假设 levelchar 为>。在内部，我们已停止使用l3doc.ist，而是使用gind.istLaTeX2e 发行版。如果您使用它，或更正 levelchar，l3doc.ist您将看到env条目正确显示，仍然会有 2 个条目，但其中一个是主标题“环境”下的子条目。

至于opt: 您使用的问题function，但那只是用于命令，它只是出于排序目的而删除第一个字符，假设它是反斜杠；因此您的条目在第二个字符“p”下排序。您运气不好，我们没有用于记录选项的环境。

目前有\DescribeOption命令，但仅此而已，我们不确定这个命令是否能在以后的版本中继续存在。

更新

我刚刚意识到我没有回答第二个问题：“为什么env显示的页码是“1”而不是2？”

嗯，它不是，它显示的代码行号为 1（直立数字），而不是使用默认包约定的页码doc。换句话说，这是一个代码文档环境，而不是用户界面描述环境。

基本上是一个缺陷（如果不是错误的话）让我们回到这一点，这实际上不是一个成品......但很明显我们应该对此做些什么。

相关内容