LaTeX/建立包文件
文件對於終端使用者來說非常重要，可以讓他們快速瞭解如何使用您的包。它們也對其他開發人員有幫助，因為它們可以使閱讀您的程式碼更容易。每種程式語言都有自己的文件編寫方式。對於 LaTeX，我們從.dtx檔案生成 pdf 文件。
.dtx字尾是documentation TeX的縮寫。它具有兩種功能
- 向用戶解釋如何使用包中的命令
- 格式化原始碼以方便閱讀
假設您想要為新建立的包編寫文件，該包名為mypackage例如。 的基本結構.dtx檔案如下所示
% \iffalse meta-comment
% Add copyright,author,version information
% here for this documentation file
% \fi
% \iffalse
%<*driver>
\ProvidesFile{mypackage.dtx}[1.0 My package]
\documentclass{ltxdoc}
\begin{document}
\DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% write normal LaTeX documentation content here
% \Finale
%
\endinput
|
當您執行pdflatex mypackage.dtx，您可以生成mypackage.pdf，即手冊。在這個 pdf 檔案中，\fi 和 \endinput 之後的全部內容都會從註釋中剝離出來，並插入到文件之間。注意，當 LaTeX 引擎第一次遇到 \DocInput 時，它會再次讀取同一個檔案，但會剝離所有以 % 開頭的行。結果是，它會忽略包含 \iffalse ...\fi 的程式碼塊。還應注意，同一個檔案的第二次傳遞也會忽略 %<driver> 和 %<*driver> 之間的魔法註釋。指示符 **driver** 表明內部內容是生成最終手冊的包裝器，您可以根據需要用其他單詞替換它們。
有一些宏需要進一步解釋
\ProvidesFile{<name>}[<version>]的工作原理類似於\ProvidesPackage{<name>}[<version>]，它將方括號中的內容寫入日誌檔案。- 元註釋用於提供.dtx檔案本身的資訊。由於您不能使用正常的 TeX 註釋，因為它們會被剝離。
- ltxdoc類似於其他文件類，並提供一些易於使用的命令來編寫包文件，如下所示。
要描述在您的包中定義的宏，您可以使用
% \begin{macro}{\mymacro}
% mymacro definition goes here
% \end{macro}
|
環境macro接受一個強制引數，即宏的名稱，並在左頁邊距處列印。您也可以使用 \DescribeMacro{mymacro} 並將額外的解釋放在正常文字中。對於新的環境描述，您可以使用 \DescribeEnv{mynewenv}。它們的區別在於索引條目型別，這將在下面說明。
在包文件檔案的序言中新增 \EnableCrossrefs（在行開頭不要加註釋）。在您想要索引出現的位置新增 \PrintIndex。您描述的所有宏都將在文件末尾打印出來。有關建立索引的常規介紹，請參見編譯索引。通常，以下構建就足夠了
makeindex -s gind.ist -o mypackage.ind mypackage.idx
ltxdoc還提供了記錄包更改的功能。要啟用此功能，請在序言中新增 \RecordChanges，並使用
\changes{v1.0}{2017/01/01}{create my package.}
|
在您想要索引出現的位置新增 \PrintChanges。更改將使用術語表支援進行記錄，呼叫makeindex從命令列
makeindex -s gglo.ist -o mypackage.gls mypackage.glo