17

Markdown の Perl モジュールで README ファイルを作成しました。Github は、この README ファイルをプレーン テキストとして扱います。ファイルの名前を「README.md」に変更してみました。これは Github では見栄えがしますが、「README」という名前のファイルを探す Perl ツールには表示されません。

README ファイルと、Markdown フォーマットを Github が正しく解釈できるようにする方法はありますか?

私が思いついた唯一の選択肢は、README と README.md の両方を用意することでしたが、手動で 2 つのファイルの同期を維持する必要はありません。

ご協力いただきありがとうございます。

4

6 に答える 6

21

README をポッドでフォーマットし、名前を README.pod に変更すると、両方の場所で機能します! 例

私の目的のために、実際にはメインポッドから README.pod を生成するだけです

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

残念ながら、外部リンクが正しく機能しないという名前の 1 つの警告はL<GitHub|http://github.com>、GitHub モジュールを探している search.cpan.org を指します。私は彼らにこの不具合を知らせようとしましたが、どこにも行きませんでした。代わりに、プレーンな外部リンク (つまり ) を使用するだけで問題なくGitHub: L<http://github.com>動作します。

良いニュースです。私が最後にチェックして以来、彼らはこれを修正したようです!

質問ですが、Perl ツールチェーンのどの部分で README ファイルが必要ですか? tarball に含める場合は、必ずファイルを MANIFEST に追加してください。含まれているはずです。

于 2012-11-02T03:10:48.570 に答える
16

PODについて聞いたことがありますか？これは、Perl の標準的なドキュメント ツールです。POD は、コード内に実際に存在する単純なテキスト ドキュメント形式です。perl に付属するコマンドの 1 つにperldocがあります。これを使用して、任意の Perl コマンドの情報を取得できます。これらを試してください：

$ perldoc File::Find
$ perldoc -f split

POD ドキュメントを組み込むには、 CPANのすべての Perl モジュールが必要です。実際、これは CPAN Web ページ自体が構築される方法です。

それで、私はこれでどこに行きますか、そしてこれはあなたにどのように役立つでしょうか?

Perl プログラムに POD ドキュメントを含める必要があります。次に、pod2textコマンドを使用して、Perl プログラムの README を作成できます。

$ pod2text myperl.pl > README

これで問題の半分が処理されます。

残りの半分はもう少しトリッキーです。システムにPod::MarkdownをCPAN からインストールする必要があります。次に、このモジュールに付属のpod2markdownコマンドを実行して、ファイルのマークダウンバージョンを作成できます。

$ pod2markdown myperl.pl > README.md

結果：

  • ドキュメントは、当然のことながら、Perl プログラム内に存在します。
  • ユーザーは、perldocプログラムを使用して、プログラムの完全なドキュメントを印刷できます。
  • pod2textツールを使用してファイルを作成できますREADME。
  • pod2markdownツールを使用してファイルを作成できますREADME.md。
  • おまけとして、Perl に付属のPod::Usageモジュールを使用して、ユーザーがパラメーターを使用してプログラムを実行したときに表示されるヘルプ テキストとして POD ドキュメント (またはその一部) を表示-helpできます。

つまり、ドキュメンテーションが存在する 1 つの場所で、いくつかのヘルパー プログラムを使用して、ファイル Github と必要なPerl ツールを作成しています。

于 2012-11-02T03:17:31.663 に答える
5

Dist::Zillaの使用を気にしないのであれば、README を完全に維持する必要はほとんどありません。たとえば、Dist::Zilla::Plugin::ReadmeFromPodは、メイン モジュールから Pod を抽出することで README ファイルを作成できます。これは、README を再度作成する必要がないことを意味します。

自分で試したことはありませんが、Dist::Zilla::Plugin::ReadmeMarkdownFromPodのようなものを見て、マークダウンで README を自動的に作成できます。

これはあなたが探している正確な答えではないかもしれませんが、この種のツールを使用すると、ドキュメントで同じことを繰り返さないようにできるため、時間を大幅に節約できると思います。

于 2012-11-02T03:14:45.847 に答える
0

Pod を含まないMarkdown を使用してモジュールを本当に配布したい場合の別の解決策は、次のとおりです。README

  • READMEファイルの名前をREADME.md
  • MANIFESTファイルの以前の変更を更新する

Pod 構文よりも Markdown 構文を知っている人が多いので、興味深い解決策になると思います。README ファイルは誰でも読めるようにすることを目的としているため、Markdown を考慮する必要があります。

于 2013-10-27T11:37:04.220 に答える
0

この問題の解決策を探していたところ、Dist::Zilla::Plugin::ReadmeAnyFromPodを使用することにしました。これは、Pod::Weaver からのタグを理解=attrしてタグ付けするためです。=method

于 2019-03-08T20:15:41.523 に答える
-9

私が思いついた唯一の選択肢は、README と README.md の両方を用意することでしたが、手動で 2 つのファイルの同期を維持する必要はありません。

次に、それらを自動的に同期しますか?

于 2012-11-02T02:36:13.243 に答える