☰

为 CTAN 准备包时，什么是良好的做法？

tag-icon • tag-icon package-writing documentclass-writing ctan
为 CTAN 准备包时，什么是良好的做法？

我正在考虑向 CTAN 提交一个包，并希望获得一些提示，以帮助我、CTAN 管理员和最终用户尽可能顺利地完成此过程。

请告诉我在执行此操作时应注意什么。特别是，我有疑问：

  1. 我不是顶尖的技术人员，所以我不太了解 .dtx 和 .ins 文件。我可以不用它们吗？只提交包含平面文件夹的 zip 文件可以吗？

  2. 我将以 PDF 格式（手动）准备软件包用户文档。我应该使用特定的文档类别吗？或者我可以使用吗memoir？

  3. 为文档提供源 LaTeX 代码有多重要？

  4. 如果我做提供文档来源，我应该“声明”先决条件包格式化手册（与先决条件相反使用包) 作为该包的先决条件？

答案1

CTAN 管理员根本不要求遵守 DTX 格式。您的代码和文档必须为可用形式。您应该添加一个简短的README文本文件，该文件可以很好地描述软件包，以便人们可以决定是否要安装它。

  1. DTX 和 INS 文件不是必需的。您可以只包含 STY 文件和 TEX 文件以供文档使用。如果您愿意，可以使用sty2dtx脚本（由我编写）用于将 STY 文件转换为 DTX 格式。

  2. 你可以使用任何你想要的类。但是，它仍然应该可以被其他人编译。

  3. CTAN 本身将包含没有来源的文档，但是，例如，只要来源不是免费提供的，TeX Live 就不会包含它（“免费文档与免费软件一样重要。”）

  4. 只需提供一个完整的主文件，该文件会加载所有必需的包，就像任何其他 LaTeX 文档一样。包及其文档文档有点“独立”。您应该将手册的包要求与实际包分开。

在我看来，大多数人只会使用 CTAN 或他们使用的 TeX 发行版中的 PDF 文件，而不会尝试自己编译它。但是，人们仍然应该能够这样做。但是，不必在某处再次明确列出所有包。带有所需\usepackage语句的正常格式的 LaTeX 文档应该没问题。当然，当人们想要自己编译文档时，他们需要安装所需的类和包。只要这些也在 CTAN 上（最好在主发行版中），就可以了。

现在我的ctanupload脚本来自动执行上传到 CTAN 的过程。

答案2

除了 Martin 的回复（我想重申对格式没有要求.dtx）之外，一个非常有用的实用程序是 Scott Pakin 的ctanify脚本，它将您的内容打包成专门为上传到 CTAN 和包含在 TeXLive 中而设计的格式。该脚本在 Linux 和 OS X 上以及 Windows 的 Cygwin 下均可立即使用。

例如，一个相当简单的包或类可能具有以下组件：

  • mypackage.sty（包裹本身）
  • mypackage.tex（包文档来源）
  • mypackage.pdf（编译后的软件包文档）
  • README（纯文本 README 文件（无扩展名））

我需要ctanify做的就是发出以下命令（假设我在包的目录中）：

ctanify --no-tds mypackage.* *.tex=doc README

这将生成一个tar.gz包含所有文件副本的文件，

默认情况下，ctanify将包含一个文件，该文件包含中的.tds.zip文件版本， 中的文档。此格式对于结构复杂的软件包很有用。对于仅包含几个文件的小型软件包，CTAN 不建议在 tarball 中包含文件，因此在此示例中，我添加了阻止包含文件的选项。.sty/tex/latex/mypackage/doc/latex/mypackage.tds.zip--no-tds.tds.zip

以下是我为该命令提供的参数的细目：

mypackage.* % will automatically deal with .sty, .cls, .pdf, .dtx and .ins
*.tex=doc % put all .tex files into the doc folder
README % include the README file (will go into the /doc folder)

我只是描述了简单的用法。当然，如果您的包或类有一组更复杂的文件，则需要适当修改该命令。例如，如果您的.tex文件是包本身的一部分，而不是文档的一部分，那么您不会使用它们*.tex，但会mypackage.tex=doc为文档源指定它们，并为其他.tex文件指定单独的规范。

答案3

有一个（小）问题可能会派上用场：根据您的包选择您的文档文件（您的 pdf）的名称，即<package>.pdf。

这允许其他人调用texdoc <package>并且命令将启动适当的文档文件。

此外，我认为 CTAN 人员很欣赏您提交的格式提示。例如，值得注意的是您的 .zip 文件是否包含 TDS 目录结构，或者仅包含组成您的包的文件 - 而没有太多的目录结构。

答案4

我只想补充一点，创建 .dtx 和 .ins 文件是一个非常简单的问题，并且是一个非常强大的工具，可以一步创建代码文档。

只需打开终端并输入

texdoc dtxtut

享受！

相关内容