☰

使用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。換句話說，這是一個程式碼文件環境，而不是一個使用者介面描述環境。

基本上是一個缺陷（如果不是錯誤），它讓我們回到了這一點：這實際上不是成品……但很明顯，我們應該對此做點什麼。

相關內容