Readme.txt vs. README.txt

21

Ho appena biforcato un progetto in Github, ho apportato le mie modifiche ecc. Questo mi ha fatto riflettere: vedo README.txt per lo più in progetti opensource e il file che ho modificato è stato Readme.txt. È una sorta di standartisation o dovrei averlo lasciato così com'è?

    
posta Tolga Ozses 04.11.2015 - 11:12
fonte

3 risposte

22

Le lettere maiuscole si distinguono e rendono il file facilmente visibile, il che ha senso perché è probabilmente la prima cosa che un nuovo utente vorrebbe vedere. (O almeno, dovrebbe aver guardato ...) Come altri hanno già detto, i nomi dei file che iniziano con una lettera maiuscola saranno elencati prima dei nomi in minuscolo in ASCIIbetical ordinamento ( LC_COLLATE=C ) che aiuta a rendere il file visibile a prima vista.

Il file README fa parte di un gruppo di file che un utente di un pacchetto software libero normalmente si aspetterebbe di trovare. Altri sono INSTALL (istruzioni per la creazione e l'installazione del software), AUTHORS (elenco dei contributori), COPYING (testo della licenza), HACKING (come iniziare per contribuire, forse includendo un elenco TODO di inizio punti), NEWS (modifiche recenti) o ChangeLog (principalmente ridondante con i sistemi di controllo della versione).

Questo è ciò che i Norme di codifica GNU hanno per dire sul file README .

The distribution should contain a file named README with a general overview of the package:

  • the name of the package;
  • the version number of the package, or refer to where in the package the version can be found;
  • a general description of what the package does;
  • a reference to the file INSTALL, which should in turn contain an explanation of the installation procedure;
  • a brief explanation of any unusual top-level directories or files, or other hints for readers to find their way around the source;
  • a reference to the file which contains the copying conditions. The GNU GPL, if used, should be in a file called COPYING. If the GNU LGPL is used, it should be in a file called COPYING.LESSER.

Poiché è sempre bene cercare la minima sorpresa dei tuoi utenti, dovresti seguire questa convenzione a meno che non ci siano motivi validi per una deviazione. Nel mondo UNIX, le estensioni dei nomi di file venivano tradizionalmente usate con parsimonia, quindi il nome canonico del file è README senza suffisso. Ma la maggior parte degli utenti probabilmente non avrebbe problemi a capire che un file chiamato README.txt ha lo stesso significato. Se il file è scritto in Markdown , potrebbe anche essere ragionevole un nome di file come README.md . Evita di utilizzare linguaggi di markup più complessi come HTML nel file README , tuttavia, perché dovrebbe essere conveniente leggere su un terminale di solo testo. Puoi indirizzare gli utenti al manuale del software o alla sua documentazione online, che potrebbe essere scritta in un formato più sofisticato, per i dettagli del file README .

    
risposta data 04.11.2015 - 14:31
fonte
18

Tradizionalmente il file veniva chiamato README in maiuscolo perché gli ambienti a riga di comando che usano l'ordinamento alfabetico avrebbero quindi messo il file in alto. Questo li rende facilmente visibili nelle grandi directory.

È molto probabilmente un "holdover" dal mondo Unix / Linux in cui scaricare sorgenti e quindi creare il tuo software. Avere file come README e INSTALL nella parte superiore della vista 'elenco contenuto di elenchi indirizzi' rende più facile vedere che ci sono, invece di dover sfogliare l'intero contenuto da un'interfaccia della riga di comando. Lo stesso principio di base funziona anche per Github (e funziona anche nelle interfacce GUI, vieni a pensarci, quindi potrebbe ancora contenere il merito)

In nessun modo una regola difficile, ma molto probabilmente qualcosa che tutti stanno facendo come un'abitudine perché altri progetti lo stanno facendo. A meno che non ci sia un motivo esplicito per NON, dovresti probabilmente usare tutte le maiuscole solo perché vedrai che viene usato in questo modo in molti altri progetti. È anche la denominazione predefinita che Github utilizza quando crei un nuovo repository.

    
risposta data 04.11.2015 - 11:54
fonte
5

README è solitamente scritto in maiuscolo. In questo modo il comando ls Unix ha posizionato il file vicino all'inizio dell'elenco delle directory (le lettere maiuscole precedono le lettere minuscole nell'ordinamento ASCII).

    
risposta data 04.11.2015 - 11:55
fonte

Leggi altre domande sui tag