17

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

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

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

谢谢你的帮助。

4

6 回答 6

21

在 pod 中格式化您的 README，将其重命名为 README.pod，然后在两个地方都可以使用！例子

出于我的目的，我实际上只是通过执行从主 pod 生成我的 README.pod

$ podselect lib/My/Main/Module.pm > README.pod

一个警告，命名的外部链接不能正常工作，L<GitHub|http://github.com>不幸的是指向 search.cpan.org 寻找 GitHub 模块。我试图告诉他们这个故障，但它让我无处可去。相反，您可以只使用普通的外部链接（即GitHub: L<http://github.com>），它们可以正常工作。

好消息，自从我上次检查以来，他们似乎已经解决了这个问题！

只是一个问题，Perl 工具链的哪些部分需要 README 文件？如果您的意思是将它包含在您的 tarball 中，请确保将文件添加到您的清单中，它应该被包含在内。

于 2012-11-02T03:10:48.570 回答
16

你听说过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命令来创建文件的降价版本：

$ pod2markdown myperl.pl > README.md

结果：

  • 您的文档应该存在于您的 Perl 程序中。
  • 用户可以使用该perldoc程序打印出您程序的完整文档。
  • 您可以使用该pod2text工具来创建README文件。
  • 您可以使用该pod2markdown工具来创建README.md文件。
  • 作为奖励，您可以使用Perl 附带的Pod::Usage-help模块将 POD 文档（或其中的一些片段）显示为帮助文本，当用户使用参数运行您的程序时会显示该帮助文本。

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

于 2012-11-02T03:17:31.663 回答
5

如果您不介意使用Dist::Zilla，您几乎可以完全不用维护 README。例如Dist::Zilla::Plugin::ReadmeFromPod可以通过从主模块中提取 Pod 来创建 README 文件。这意味着永远不必再次编写自述文件。

我自己从未尝试过，但您可以查看类似Dist::Zilla::Plugin::ReadmeMarkdownFromPod的内容，以在降价中自动创建您的 README。

这可能不是您正在寻找的确切答案，但我认为使用这种工具可以为您节省大量时间，因为它可以让您避免在文档中重复自己。

于 2012-11-02T03:14:45.847 回答
0

如果您真的想README使用不涉及 Pod的 Markdown 分发模块，另一种解决方案是：

  • 将您的README文件重命名为README.md
  • MANIFEST更新文件中的先前更改

我认为这可能是一个有趣的解决方案，因为比 Pod 了解 Markdown 语法的人更多。由于 README 文件的目的是任何人都可以阅读，因此应考虑使用 Markdown。

于 2013-10-27T11:37:04.220 回答
0

我只是在寻找这个问题的解决方案，并决定使用Dist::Zilla::Plugin::ReadmeAnyFromPod，因为它理解=attr和=method标记来自 Pod::Weaver。

于 2019-03-08T20:15:41.523 回答
-9

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

然后自动使它们保持同步？

于 2012-11-02T02:36:13.243 回答