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

Question

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

有什么方法可以同时拥有自述文件,并且Github可以正确解释我的Markdown格式吗？

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

谢谢你的帮助.

Answer 1

在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中,只需确保将文件添加到你的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命令来创建文件的markdown版本:

$ pod2markdown myperl.pl > README.md

结果:

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

因此,您的文档存在的地方,并且您正在使用几个帮助程序来创建文件Github以及您使用的任何Perl工具.

Answer 3

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

我自己从未尝试过,但你可以看看像Dist :: Zilla :: Plugin :: ReadmeMarkdownFromPod这样的东西,在markdown中自动创建自述文件.

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