Question

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

我有没有办法两个一个README文件，并且Github能正确解释我的Markdown格式？

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

感谢您的帮助。

Answer 1

在pod中格式化README，将其重命名为README.pod，然后将其重命名为works两个位置！ Example

出于我的目的，我实际上只是通过

从主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中，只需确保将文件添加到你的MANIFEST中，它应该被包含在内。

Answer 2

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

$ perldoc File::Find
$ perldoc -f split

CPAN中的所有Perl模块都需要包含POD文档。实际上，这就是CPAN网页本身的构建方式。

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

您应该在Perl程序中包含POD文档。然后，您可以使用pod2text命令为Perl程序创建自述文件：

$ pod2text myperl.pl > README

处理问题的一半。

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

$ pod2markdown myperl.pl > README.md

结果：

您的文档应该存在于您的Perl程序中。
用户可以使用perldoc程序打印完程序的完整文档。
您可以使用pod2text工具创建README文件。
您可以使用pod2markdown工具创建README.md文件。
作为奖励，您可以使用Perl附带的Pod::Usage模块将POD文档（或其中的部分内容）显示为当用户使用{{1运行程序时显示的帮助文本参数。

因此，您的文档存在的地方，并且您正在使用一些帮助程序来创建文件Github以及您使用的任何 Perl工具。

Answer 3

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

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

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

Answer 4

另一个解决方案，如果您真的希望使用Markdown README分发您的模块，而不涉及Pod，则：

将您的README文件重命名为README.md
更新MANIFEST文件

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

Answer 5

我只是在寻找解决此问题的方法，因此决定使用Dist::Zilla::Plugin::ReadmeAnyFromPod，因为它可以理解Pod :: Weaver的=attr和=method标签。

Answer 6

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

然后自动保持同步？

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

6 个答案: