perl - 如何使我的 Perl 模块的 README 文件与 Github 的 Markdown 显示兼容？

Question

我在 Markdown 的 Perl 模块中编写了 README 文件。 Github 将此 README 文件视为纯文本。我尝试将文件重命名为“README.md”——这在 Github 上看起来很棒，但对于查找名为“README”的文件的 Perl 工具来说是不可见的。

有什么方法可以让我同时拥有一个 README 文件，并让 Github 正确解释我的 Markdown 格式？

我能想到的唯一选择是同时拥有一个 README 和一个 README.md，但我不想手动保持这两个文件同步。

谢谢你的帮助。

Answer 1

你听说过POD ?这是 Perl 中的标准文档工具。 POD 是一种简单的文本文档格式，实际上存在于您的代码中。 perl 附带的命令之一是 perldoc .您可以使用它来获取任何 Perl 命令的信息。试试这些:

$ perldoc File::Find
$ perldoc -f split

CPAN 中的所有 Perl 模块需要合并 POD 文件。事实上，这就是 CPAN 网页本身的构建方式。

那么，我要去哪里，这对你有什么帮助？

您应该在 Perl 程序中包含 POD 文档。然后，您可以使用 pod2text为您的 Perl 程序创建 README 的命令:

$ pod2text myperl.pl > README

这解决了你一半的问题。

另一半有点棘手。您需要从 CPAN 安装 Pod::Markdown在您的系统上。然后，您可以运行 pod2markdown此模块附带的用于创建文件的 Markdown 版本的命令:

$ pod2markdown myperl.pl > README.md

结果:

您的文档应该存在于您的 Perl 程序中。

用户可以使用perldoc程序打印出您的程序的完整文档。

您可以使用 pod2text创建您的README的工具文件。

您可以使用 pod2markdown创建您的README.md的工具文件。

作为奖励，您可以使用 Pod::Usage Perl 附带的模块，用于将 POD 文档(或其中的一些片段)显示为帮助文本，当用户使用 -help 运行程序时会显示该帮助文本。范围。

因此，在您的文档所在的地方，您正在使用几个帮助程序来创建文件 Github 和您使用的任何 Perl 工具。