LaTeX-Workshop 中编译 .dtx 文件的正确方法

在使用 LaTeX-Workshop 插件时，许多用户会遇到编译 .dtx 文件失败的问题。这类文件是 LaTeX 文档类或宏包的源代码文件，需要特殊的编译方式。

问题现象

当用户尝试通过点击"Compile Recipe Button"直接编译 .dtx 文件时，通常会遇到类似以下的错误信息：

Latexmk: Could not find file '/path/to/your/file'

原因分析

这种编译失败的主要原因是 .dtx 文件需要先被提取（extract）出实际的 .tex 文件，然后才能进行编译。直接编译 .dtx 文件会导致 LaTeX 引擎无法识别文件内容。

解决方案

方法一：使用正确的占位符

在 LaTeX-Workshop 的配置中，确保使用正确的占位符：

{
  "latex-workshop.latex.tools": [
    {
      "name": "pdfLaTeXmk",
      "command": "latexmk",
      "args": [
        "-pdflatex",
        "-synctex=1",
        "-shell-escape",
        "%DOCFILE%",
        "-interaction=nonstopmode",
        "-file-line-error"
      ]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "pdfLaTeXmk",
      "tools": ["pdfLaTeXmk"]
    }
  ]
}

关键区别在于将 %DOC% 改为 %DOCFILE%，这样可以正确处理 .dtx 文件的编译流程。

方法二：手动提取和编译

对于复杂的 .dtx 文件，可能需要分步处理：

1. 首先使用 tex 命令提取 .ins 文件：

   tex yourfile.ins
   

2. 然后编译生成的 .tex 文件：

   pdflatex yourfile.tex
   

方法三：创建自定义编译链

可以在 LaTeX-Workshop 中创建专门的 .dtx 编译链：

{
  "latex-workshop.latex.tools": [
    {
      "name": "extract-dtx",
      "command": "tex",
      "args": ["%DOCFILE%.ins"]
    },
    {
      "name": "compile-dtx",
      "command": "pdflatex",
      "args": ["%DOCFILE%.tex"]
    }
  ],
  "latex-workshop.latex.recipes": [
    {
      "name": "Process DTX",
      "tools": ["extract-dtx", "compile-dtx"]
    }
  ]
}

最佳实践建议

1. 对于 .dtx 文件开发，建议使用专门的开发环境或脚本
2. 保持 .dtx 和 .ins 文件在同一目录
3. 在项目文档中明确说明编译步骤
4. 考虑使用 Makefile 或类似的构建工具自动化编译流程

通过以上方法，可以有效地解决 LaTeX-Workshop 中编译 .dtx 文件的问题，提高文档类或宏包的开发效率。