Readme.txt vs. README.txt


33

Acabei de bifurcar um projeto no Github, fiz minhas alterações etc. Isso me fez pensar: eu vejo principalmente README.txt em projetos de código-fonte aberto e o arquivo que editei foi o Readme.txt. Isso é algum tipo de padronização ou devo ter deixado como está?


All-caps provavelmente teve seu início no MS-DOS, todas em minúsculas provavelmente do legado unix. Não tenho certeza sobre a primeira letra maiúscula - raízes Mac, talvez. No final, isso realmente não importa, exceto por uma questão de limpeza ou estilo.
Lawrence

Respostas:


29

As letras maiúsculas se destacam e tornam o arquivo facilmente visível, o que faz sentido, porque é provavelmente a primeira coisa que um novo usuário gostaria de ver. (Ou, pelo menos, deveria ter olhado para…) Como já foi dito, os nomes de arquivos iniciados com uma letra maiúscula serão listados antes dos nomes em minúsculas na classificação ASCIIbetics ( LC_COLLATE=C), o que ajuda a tornar o arquivo visível à primeira vista.

O READMEarquivo faz parte de vários arquivos que um usuário de um pacote de software livre normalmente esperaria encontrar. Outras são INSTALL(instruções para compilar e instalar o software), AUTHORS(lista de colaboradores), COPYING(texto da licença), HACKING(como começar a contribuir, talvez incluindo uma lista TODO de pontos de partida), NEWS(alterações recentes) ou ChangeLog(principalmente redundantes com sistemas de controle de versão).

É o que os Padrões de Codificação GNU têm a dizer sobre o READMEarquivo.

A distribuição deve conter um arquivo nomeado READMEcom uma visão geral do pacote:

  • o nome do pacote;
  • o número da versão do pacote ou consulte onde o pacote pode ser encontrado;
  • uma descrição geral do que o pacote faz;
  • uma referência ao arquivo INSTALL, que por sua vez deve conter uma explicação do procedimento de instalação;
  • uma breve explicação de qualquer diretório ou arquivo incomum de nível superior ou outras dicas para os leitores encontrarem o caminho da fonte;
  • uma referência ao arquivo que contém as condições de cópia. A GNU GPL, se usada, deve estar em um arquivo chamado COPYING. Se o GNU LGPL for usado, ele deverá estar em um arquivo chamado COPYING.LESSER.

Como é sempre bom procurar a menor surpresa de seus usuários, você deve seguir esta convenção, a menos que haja razões convincentes para um desvio. No mundo UNIX, as extensões de nome de arquivo eram tradicionalmente usadas com moderação, de modo que o nome canônico do arquivo não possui READMEsufixo. Mas a maioria dos usuários provavelmente não teria problemas para entender que um arquivo chamado README.txttem o mesmo significado. Se o arquivo estiver escrito no Markdown , um nome de arquivo como README.mdtambém pode ser razoável. Evite usar linguagens de marcação mais complicadas, como HTML, noREADMEarquivo, no entanto, porque deve ser conveniente ler em um terminal somente de texto. Você pode indicar aos usuários o manual do software ou a documentação on-line, que pode ser escrita em um formato mais sofisticado, para obter detalhes do READMEarquivo.


20

Tradicionalmente, o arquivo era chamado README em maiúsculas, porque os ambientes de linha de comando que usam a ordem alfabética colocavam o arquivo no topo. Isso os torna facilmente visíveis em grandes diretórios.

É muito provável que haja uma retração do mundo Unix / Linux, onde você faria o download de fontes e, em seguida, construiria seu software. Ter arquivos como README e INSTALL na parte superior da visualização 'list directory contents' facilita a visualização de que eles estão lá, em vez de ter que procurar todo o conteúdo em uma interface da linha de comandos. O mesmo princípio básico também funciona para o github (e na verdade também funciona em interfaces GUI, pense nisso, para que ainda tenha mérito).

De maneira alguma uma regra difícil, mas muito provavelmente algo que todo mundo está fazendo como um hábito, porque outros projetos estão fazendo isso. A menos que haja alguma razão explícita para NÃO, você provavelmente deve usar todos os limites apenas porque verá isso sendo usado dessa maneira em muitos outros projetos. É também a nomeação padrão que o Github usa quando você cria um novo repositório.


Eu sempre pensei que todas as letras maiúsculas eram uma forma de ênfase, assim como você tem as seções de letras maiúsculas no legal.
Lars Viklund #

1
Em uma interface de linha de comando, os arquivos que vão para o topo da lista são, na verdade, os que primeiro saem da visualização, portanto, às vezes, esses são os arquivos menos visíveis. A menos que você sempre faça algo assim ls -l | less.
21420 Marc Marie Leeuwen

6

O README geralmente é escrito em maiúsculas. Dessa maneira, o lscomando Unix colocou o arquivo próximo ao início da lista de diretórios (as letras maiúsculas vêm antes das letras minúsculas na ordem ASCII).


3
Essa foi a razão histórica, mas lsnormalmente não é assim nos sistemas modernos.

1
@ dan1111 Certo! Obrigado (apenas para tentar ... LC_COLLATE="en_US.ascii" ; ls -lvs LC_COLLATE="en_US.UTF-8" ; ls -l)
manlio
Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.