Readme.txt与README.txt


33

我刚刚在Github中创建了一个项目,进行了更改等。这使我感到奇怪:我在开源项目中主要看到README.txt,而我编辑的文件是Readme.txt。这是某种形式的标准化还是我应该保留它?


全大写字母可能始于MS-DOS,所有小写字母都可能来自UNIX传统。不确定首字母大写-也许是Mac的根。最后,除了整理或风格问题外,这并不重要。
劳伦斯

Answers:


29

全大写字母突出显示并使文件容易可见,这很有意义,因为这可能是新用户要看的第一件事。(或者,至少应该检查一下……)正如其他人已经说过的那样,在ASCIIbetical排序(LC_COLLATE=C)中,以大写字母开头的文件名将在小写字母之前列出,这有助于使文件乍一看。

README文件是自由软件包用户通常期望找到的一堆文件的一部分。其他是INSTALL(构建和安装软件的说明),AUTHORS(贡献者列表),COPYING(许可文本),HACKING(如何开始进行贡献,可能包括起点的TODO列表),NEWS(最近的更改)或ChangeLog(大多与版本控制系统)。

这就是GNU编码标准必须对README文件说的话。

发行版应包含一个文件README,该文件的名称为该软件包的概述:

  • 包装名称;
  • 软件包的版本号,或指的是在软件包中可以找到该版本的位置;
  • 包装的一般说明;
  • 对文件的引用INSTALL,其中应包含对安装过程的说明;
  • 对任何异常的顶级目录或文件的简要说明,或其他提示,供读者找到使用源代码的方式;
  • 对包含复制条件的文件的引用。如果使用了GNU GPL,则应将其放在名为的文件中COPYING。如果使用了GNU LGPL,则它应位于名为的文件中COPYING.LESSER

由于争取用户的最小惊喜总是好的,因此,除非有令人信服的理由导致偏差,否则应遵循此约定。在UNIX世界中,传统上很少使用文件扩展名,因此文件的规范名称README不带任何后缀。但是大多数用户可能会很容易理解,名为的文件README.txt具有相同的含义。如果文件是用Markdown编写的,则文件名like README.md也可能是合理的。避免在HTML中使用更复杂的标记语言(例如HTML)README但是,因为在纯文本终端上阅读应该很方便。您可以为用户提供该软件的手册或其在线文档,这些手册可能以更复杂的格式编写,以获取README文件中的详细信息。


20

传统上,该文件以大写形式称为README,因为使用字母顺序的命令行环境会将文件放在顶部。这使得它们很容易在大目录中可见。

这很可能是Unix / Linux世界的遗留物,您可以在其中下载源代码然后构建软件。在“列表目录内容”视图的顶部具有诸如README和INSTALL之类的文件,可以更轻松地看到它们在其中,而不必从命令行界面浏览整个内容。相同的基本原理也适用于github(并且实际上也可以在GUI界面中使用,请考虑一下,因此它可能仍然有价值)

绝非硬性规定,但很可能是每个人都习惯这样做,因为其他项目正在这样做。除非有明确的理由不这样做,否则您可能应该使用所有大写字母,原因是您会在许多其他项目中看到这种用法。这也是创建新存储库时Github使用的默认命名。


我一直认为全大写是一种强调形式,就像您在legalese中如何使用大写部分一样。
拉尔斯·维克伦德

1
在命令行界面上,到达列表顶部的文件实际上是首先滚动出视图的文件,因此有时它们是最不可见的文件。除非你总是做类似的事情ls -l | less
Marc van Leeuwen

6

自述文件通常以大写形式编写。这样,lsUnix命令将文件放在目录列表的开头附近(大写字母在ASCII顺序中位于小写字母之前)。


3
这是历史原因,但ls在现代系统上通常不采用这种方式。

1
@ dan1111对!谢谢(只是尝试... LC_COLLATE="en_US.ascii" ; ls -lvs LC_COLLATE="en_US.UTF-8" ; ls -l
manlio
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.