以这种格式编写包的推荐方法是什么.dtx
?包作者通常只编写第一个,还是使用某种工具从文件中.dtx
创建?我知道这两种方法都有效,但最好的入门方法是什么?我目前正在尝试理解可用的文档,但就像 LaTeX 一样,这感觉就像它的学习曲线与砖墙一样。.dtx
.sty
LaTeX 可以加载.dtx
文件来代替.sty
文件吗,还是必须先进行预处理?
我以前编写的包只是\usepackage
各种便利宏的集合,但现在我正在尝试编写一些更有用的东西,我想在某个时候分发它,并回馈社区。
答案1
免责声明:我是一名软件包开发人员,但仅供内部使用(我/我的机构;到目前为止有 9 个软件包和 3 个课程)。我还没有将软件包上传到 CTAN。因此,这不是更有经验的 LaTeX 开发人员可能会给出的建议。
dtx
我通常将我的软件包(最后的文件,用作l3build
工作环境)的开发分为三个阶段:
第一阶段:树立正确的概念
此阶段涉及反复试验。我使用我想要的语法设置了一个测试文档,并为所有未定义的控制序列创建了“虚拟命令”,这些命令实际上什么也不做。
然后我将一个基本包设置为一个.sty
文件(使用expl3
语法)。现在我尝试实现所需的基本宏以及包选项。对于每个实现的宏,我都会删除我的虚拟宏。
此步骤持续到我认为我的包的基本功能已实现。在实现过程中,您可以轻松进行测试。
第二阶段:记录你的进步
在此步骤中,我将代码转换为dtx
格式(使用l3doc
功能)。此步骤非常繁琐,但很重要。基本上,您将注释结构添加到代码中。此时,我还将包设为 git 项目以进行版本控制。
不要忘记写下一些关于你的包的基本概念和简单的路线图,特别是当你知道在开发过程中会暂停的时候。
在编写文档时,我利用l3build
来为我构建文档。通常,我还将我的软件包包含在我的dtx
文档中(其中可能包含示例),因此可以很快识别出严重的问题。l3build
还允许您创建测试文件,这对于更复杂的软件包来说是一个不错的选择。1
第三阶段:进一步开发、测试和发布
您的dtx
文件已准备好添加其他功能和更新现有宏。我正在直接更改 dtx 文件(如果出现问题,git 是我的保险)。l3build
每次运行时也会创建包,如果您告诉它2,您也可以复制文件.sty
并事先用它测试一些修改。
当我将包包含在dtx
文档中并通常为包的功能编写示例时,我也会在扩展包时注意到一些问题。
如果您认为功能已经可用,请将您的dtx
文件转换为完整文档(供用户使用)并考虑一些测试用例(用户可能犯错的地方)。测试包。我通常将步骤 1 中的测试文件作为入门文件。
然后,您可以使用l3build
并cmdcheck
进行dtx
构建ctan
。此时,您可以创建一个 git 标签(如果您使用 git)。
1对于类来说,执行此操作稍微困难一些,因为您可能不会用类编写文档,但您可能希望将一些示例文件包含到文档中,该文件在每次文档构建时都会编译以进行测试。
2您基本上可以将.ins
文件包含到文件中.dtx
,并在每次运行时创建包。 那里有如何执行此操作的示例。
答案2
首先要记住的是,你不要有使用.dtx
格式在包代码中包含注释:您只需使用 即可.sty
。假设您确实想使用.dtx
来允许排版代码,ETC。,那么你仍然可能能够.dtx
直接使用。如果源文件中只有一个“目标”,则情况确实如此:只有注释和“实时”代码。但是,大多数.dtx
文件都包含“驱动程序”(以允许排版代码),因此实际上至少有两个目标。在此阶段,您有提取出来.sty
以便能够与 LaTeX 一起使用。
如果我们采用这种常见情况,您可以通过.tex
在与同一位置放置一个简单的文件.dtx
并使用 shell escape 来启用第一行进行测试,例如
\immediate\write18{tex mypkg.dtx}
\documentclass{article}
\usepackage{mypkg}
% Tests
这当然具有非零的安全隐患,并且往往有点“脆弱”:理想情况下,您需要一个用于测试的沙箱,将提取的代码与其他所有内容分开。
显而易见的方法是脚本提取,也许安装在本地树中并进行测试。有几个脚本可以做到这一点,但毫不奇怪,我会指出l3build
来自 LaTeX3 项目。这是基于 Lua 的脚本,允许对打包的代码进行完全自动化测试:根据您的需要,您可能只需解压并使用简单.tex
文件进行测试,或者可以创建一个或多个自动测试输入/输出集(.lvt
/.tlg
文件)。
在创建.dtx
文件方面,有一些脚本可以“填补空白”,但最终格式的目的是为文档和代码提供有用的注释/描述。这只有你实际编写材料才能做到!