Readme.txtとREADME.txt


33

私はGithubでプロジェクトを分岐し、変更などを行いました。これにより、オープンソースプロジェクトでほとんどREADME.txtが表示され、編集したファイルはReadme.txtでした。これはある種の標準化ですか、それともそのままにしておくべきですか?


すべて大文字はおそらくMS-DOSで始まり、すべて小文字である可能性があります。大文字の最初の文字についてはわからない-Macのルーツ、おそらく。結局のところ、整頓やスタイルの問題を除いて、それは本当に重要ではありません。
ローレンス

回答:


29

大文字がすべて目立つため、ファイルを簡単に表示できます。これは、おそらく新しいユーザーが最初に見たいと思うことになるためです。(または、少なくとも、見ておくべきでした...)他の人がすでに言ったように、大文字で始まるファイル名はASCIIbeticalソート(LC_COLLATE=C)で小文字名の前にリストされ、一目でファイルを見えるようにします。

このREADMEファイルは、フリーソフトウェアパッケージのユーザーが通常見つけることを期待する一連のファイルの一部です。その他にはINSTALLAUTHORS(ソフトウェアのビルドとインストールの手順)、(貢献者のリスト)、COPYING(ライセンステキスト)、HACKING(おそらく開始点のTODOリストを含む、貢献の開始方法)、NEWS(最近の変更)、またはChangeLog(ほとんどが冗長です)バージョン管理システム)。

これは、GNUコーディング標準READMEファイルについて述べなければならないことです。

ディストリビューションにはREADME、パッケージの一般的な概要が記載されたファイルが含まれている必要があります。

  • パッケージの名前。
  • パッケージのバージョン番号、またはパッケージ内のどこにバージョンがあるかを参照します。
  • パッケージの機能の一般的な説明。
  • ファイルへの参照にINSTALLは、インストール手順の説明が含まれている必要があります。
  • 異常なトップレベルのディレクトリまたはファイルの簡単な説明、または読者がソースを回避するためのその他のヒント。
  • コピー条件を含むファイルへの参照。GNU GPLを使用する場合は、というファイルに含める必要がありますCOPYING。GNU LGPLを使用する場合は、というファイルにある必要がありますCOPYING.LESSER

ユーザーの驚かないように努力することは常に良いことなので、逸脱の説得力のある理由がない限り、この規則に従うべきです。UNIXの世界では、ファイル名拡張子は伝統的に控えめに使用されていたため、ファイルの正規名にはREADME接尾辞がありません。しかし、ほとんどのユーザーはおそらく、指定されたファイルREADME.txtが同じ意味を持っていることを理解することに問題はないでしょう。ファイルがMarkdownで記述されている場合、次のようなファイル名README.mdも妥当です。HTMLのようなより複雑なマークアップ言語の使用は避けてくださいREADMEただし、ファイルはテキストのみの端末で読むと便利なはずです。READMEファイルの詳細については、より洗練された形式で記述されている可能性のあるソフトウェアのマニュアルまたはオンラインドキュメントをユーザーに示すことができます。


20

従来、ファイルは大文字でREADMEと呼ばれていました。これは、アルファベット順を使用するコマンドライン環境がファイルを先頭に配置するためです。これにより、大きなディレクトリに簡単に表示されます。

これはおそらく、ソースをダウンロードしてからソフトウェアをビルドするUnix / Linuxの世界から持ち越されたものです。「ディレクトリコンテンツの一覧」ビューの上部にREADMEやINSTALLなどのファイルがあると、コマンドラインインターフェイスからコンテンツ全体を参照する代わりに、それらがそこにあることが簡単にわかります。同じ基本原則はgithubでも機能します(実際にはGUIインターフェースでも機能しますが、考えてみるとメリットがあります)

決して厳しいルールではありませんが、他のプロジェクトがそれをやっているので、誰もが習慣としてやっている可能性が非常に高いです。しない明確な理由がない限り、他の多くのプロジェクトでそのように使用されていることがわかるからといって、おそらくすべて大文字を使用するべきです。また、新しいリポジトリを作成するときにGithubが使用するデフォルトの命名法です。


私はいつも、大文字のセクションがリーガルであるのと同じように、すべて大文字が強調の形だと思ってきました。
ラースヴィクランド

1
コマンドラインインターフェースでは、リストの一番上に表示されるファイルは、実際には最初にビューからスクロールするファイルです。そのため、これらは最も見えにくいファイルです。いつものようなことをしない限りls -l | less
マークヴァンレーウェン

6

READMEは通常大文字で書かれています。このようにして、lsUnixコマンドはファイルをディレクトリリストの先頭近くに配置しました(ASCII順で大文字が小文字の前に来ます)。


3
これが歴史的な理由でしたが、ls通常、現代のシステムではそのようには分類されません。

1
@ dan1111そう!ありがとう(試してみてください... LC_COLLATE="en_US.ascii" ; ls -lLC_COLLATE="en_US.UTF-8" ; ls -l
マンリオ
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.