☰

背景

tag-icon • tag-icon texlive package-writing ctan python
背景

我正准备发布我的第一个包，但不确定最好的方法是什么。我了解标准的 CTAN 发布方法，但我正在处理一个不太典型的情况，因为我的包涉及 Python 脚本和（对于 Windows）批处理文件。我不确定这些可能需要什么特殊处理。

背景

我的软件包允许在文档中排版 Python 代码和/或将其保存到执行它的外部文件中（然后可以将输出拉回到 LaTeX）。基本上，它是python.sty、SageTeX和的大多数功能的组合minted，重点是速度（所有内容都经过哈希处理，仅在更改时运行，并且并行运行）和可用性（所有 Python 错误都可以在 LaTeX 编辑器中报告，并带有正确的行号）。

要使其工作，需要运行latex file.tex，pythontex.bat file（或pythontex.py file，取决于操作系统；.bat基本上只是调用.py），然后latex file.tex。问题是需要安装包，以便pythontex.bat（或pythontex.py）可以在不指定完整路径的情况下运行（即，位于系统路径中的某个位置）。它们需要表现得像 TeX Live 文件bin/夹中的二进制文件一样。这是必要的，以便它们可以通过 LaTeX 编辑器或命令行轻松调用。

还有一个额外的复杂因素。该包需要两个额外的 Python 文件，pythontex_utils.py和pythontex_types.py。这些文件需要能够被任何 Python 脚本导入。这意味着要么需要将它们安装为 Python 包（以便 Python 可以自动找到它们），要么我需要一种方法来自动确定它们位置的完整路径（以便可以使用路径导入它们）。

可能的方法

  • SageTeX将所有 Sage/Python 内容捆绑在 Sage 中。是否让文件.sty可访问取决于用户。我可以采取类似的方法：将我的代码放入 Python 包中，并希望为文件提供某种自动安装程序.sty。这将使处理 Python 方面的事情（版本 2.x 与 3.x 等）变得更容易，但也意味着该包不在 CTAN 上。
  • 我可以把所有东西都放在 CTAN 上，除了必须可导入的 Python 内容，然后将其单独发布为 Python 包。主要缺点是用户必须安装两样东西。
  • 如果有令人满意的方法解决我的所有问题，我可以把所有问题都放在 CTAN 上。这种方法更可取。

概括

  • 我想要一种方法来将.py或.bat文件作为包安装的一部分进行安装，以便它可以像 TeX Live 文件夹中的可执行文件一样启动bin/（因为该文件夹已添加到系统路径中）。
  • 这可能是对第一点的重述，但任何关于 TeX Live 如何处理脚本的说明都将非常有用。例如，是一个 Perl 脚本，但至少在 TeX Live 的 Windows 安装中，在 下sty2dtx还有一个，它会启动 Perl 脚本。如果知道这些二进制文件是来自软件包作者还是 TeX Live，那就太好了。我怀疑是 TeX Live（至少对于， CTAN 上没有）。sty2dtx.exebin/sty2dtx.exe
  • 除非我还发布一个单独的 Python 包，否则我需要一种方法来获取安装 LaTeX 包的完整路径，仅基于包名称，这样我的程序就可以找到必须导入的 Python 文件。

答案1

根据您软件包的功能，我认为它更属于 TeX 领域而非 Python 领域，因此我同意您认为 CTAN 是放置它的最佳位置。您的问题涉及几个不同的方面，我将在下面尽可能全面和全面地回答这些问题。

脚本与二进制文件

首先，好消息是脚本比编译程序更容易集成到 TeX 发行版中。要将后者纳入 TeX Live 或 MiKTeX，最好通过相应的邮件列表与发行版维护者取得联系。

提交至 CTAN

您需要决定是否将您的包作为平面.zip档案提交给 CTAN，还是以.tds.zip 总溶解固体格式（另请参阅TDS 提交指南)。TDS 避免了文件布局的歧义，但一定要遵守规范——.zip最好是没有子目录的平面布局，而不是混乱的布局.tds.zip。 测试你的.tds.zip提交前例如，安装到 TEXMFHOME 并查看一切是否正常（请参阅下文如何测试可执行脚本）。以下是我建议的软件包布局pythontex：

doc/
   +-- latex/ 
            +-- pythontex/
                         +-- pythontex.pdf
                         +-- README
scripts/
       +-- pythontex/
                    +-- pythontex.bat
                    +-- pythontex.py
                    +-- pythontex_types.py
                    +-- pythontex_utils.py
source/
      +-- latex/ 
               +-- pythontex/
                            +-- pythontex.dtx
tex/
   +-- latex/ 
            +-- pythontex/
                         +-- pythontex.sty

您应该将所有软件包文件都包含在存档中，而不仅仅是源文件（例如，不仅包括.dtx，还包括.sty从中派生的文件）。您还应该包含一个简短而清晰的README文件，其中指定软件包的用途、其许可证（需要免费包含在 TL 中）、其内容（文件及其用途）以及安装和使用软件包所需的任何其他要求（例如，像 Python 这样的外部依赖项）。

可执行脚本

包含可执行文件的目录（即添加到 的目录PATH）未包含在 TDS 规范中，但作为软件包作者，您无需担心这一点。只需将您的脚本放在 下scripts/<package name>，并在软件包中明确说明README哪个脚本是要执行的主程序。然后，TeX 发行版将在目录中添加符号链接（Unix 上的 TL）或启动包装器（win32、TL 和 MiKTeX）bin。

是否包含用于启动脚本的包装器取决于您。原则上，现在 TeX Live 和 MiKTeX 不需要这样做 - 两者都有自己的专用包装器用于此目的。但是，有些用户可能需要直接从 CTAN 安装您的软件包（例如，与较旧的 TL 版本一起使用），因此至少添加一个.bat适用于 Windows 的包装器（参见下面的示例）可能会很好。对于 Unix，只需启动您的主脚本#!/usr/bin/env python（为了系统可移植性，/usr/bin/env建议使用硬编码解释器的绝对路径）。

对于 Windows，我可以建议以下包装器（如果保存，pythontex.bat它将执行pythontex.py脚本）。

@echo off
setlocal enableextensions
rem assuming the main script is in the same directory
if not exist "%~dpn0.py" (
  echo %~nx0: main script "%~dpn0.py" not found>&2
  exit /b 1
)
rem check if interpreter is on the PATH
for %%I in (python.exe) do set "PYTHONEXE=%%~$PATH:I"
if not defined PYTHONEXE (
  echo %~nx0: Python interpreter not installed or not on the PATH>&2
  exit /b 1
)
"%PYTHONEXE%" "%~dpn0.py" %*

正如我所提到的，TeX Live 和 MiKTeX 使用它们自己的方法来启动脚本，尽管我只熟悉 TL 方面的事情。TeX Live 使用runscript.tlu实用程序来实现这一点，用户也可以将其用于他们自己的自定义或手动安装的脚本。包作者也可以使用它来进行测试，例如，您可以测试您的代码是否正常工作。有关详细信息，请参阅（添加开关以了解实际实现的所有细节）.tds.zip的输出。以下是其中的摘录：runscript -h-v

The following script types and their file extensions are currently
supported and searched in that order:

  Lua      (.tlu;.texlua;.lua) --  included
  Perl     (.pl)               --  included
  Ruby     (.rb)               --  requires installation
  Python   (.py)               --  requires installation
  Tcl      (.tcl)              --  requires installation
  Java     (.jar)              --  requires installation
  VBScript (.vbs)              --  part of Windows
  JScript  (.js)               --  part of Windows
  Batch    (.bat;.cmd)         --  part of Windows

Finally, Unix-style extensionless scripts are searched as last and
the interpreter program is established based on the she-bang (#!)
specification on the very first line of the script.  This can be
an arbitrary program but it must be present on the search path.

如果可能的话，建议用 Lua 编写新的实用程序，因为 LuaTeX 的出现使 Lua 解释器在所有平台上都可立即使用。紧随其后的是 Perl，它在 win32 上随 TL 一起提供。其他任何东西都必须在 Windows 上单独安装。

查找脚本/包资源

复杂脚本可能分散在多个文件中，对于如何定位这些文件，没有灵丹妙药。在 TeX Live 中查找文件的标准方法是使用 Kpathsea 及其kpsewhich实用程序（现在也适用于 MiKTeX），例如，如果在 TEXMF 树之一下的子目录中找到它，kpsewhich -format texmfscripts pythontex_utils.py它将输出完整路径。在 LuaTeX 中，Kpathsea 库是内置的，可以直接访问。可能还有其他一些更好的方法，它们特定于 Python、Perl 等，但这应该在其他地方询问。pythontex_utils.pyscripts

答案2

  1. 关于平面.zip与.tds.zip，CTAN 现在拒绝仅包含 TDS 结构的上传，无论是否为.zip。他们现在要求为主树创建一个“浏览友好”的相对平面结构。

  2. 关于创建.tds.zip，我强烈反对在这里这样做。一般来说，除非有具体原因这样做。通常没有。但这确实与原始问题无关。

  3. 关于脚本如何找到它们的模块，我刚刚就此话题给另一个人（Michael Palmer）写了一篇相当长的回复。请参阅从http://tug.org/pipermail/tex-live/2012-September/032417.html。

如果您想进一步讨论，请随时给我写信或发邮件至 tex-live 邮件列表。（至于 MiKTeX，我不知道。）

最好的，卡尔（[电子邮件保护]）

答案3

这回答了您关于如何获取脚本位置的最后一个问题。解决方案依赖于 ConTeXt 包装器脚本mtxrun或 ConTeXt Lua 库resolvers。

我是 t-vimConTeXt 中的模块，它使用 vim 编辑器来突出显示代码的语法（类似于pygmentsLaTeX 中的包）。作为此模块的一部分，我分发了一个2context.vimvim 脚本，它执行实际的转换。我将脚本包含在与常规.tex文件相同的目录中（我最初（~2008/9）使用了script子目录，但 kpathsea 无法搜索它；我从未再次检查以查看情况是否发生了变化），并让 kpathsea 找出文件的位置。

粗略地说，在 MkII （pdftex后端）中，对 vim 的调用是：

mtxrun --direct -c vim "source kpse:2context.vim" <other options>

ConTeXt 包装器脚本mtxrun扩展kpse:...为 返回的完整路径kpsewhich。这也适用于 LaTeX，但您将引入对 的依赖context。

在 MkIV（luatex已支持）中，我使用 ConTeXtkpse库来获取文件在 TeX 端的位置：

  \ctxlua{context.setvalue("vimtyping@script_name",resolvers.resolve("full:2context.vim"))}

其中resolvers.resolve("full:...")返回文件的完整路径。然后我使用以下命令调用 vim：

  vim -c "source \vimtyping@script_name" <other options>

使用这种方法，脚本可以包含在 kpathsea 可以找到的任何目录中，用户不必单独安装它。

相关内容