Rewrite and reformat documentation of languages.yml

lib/linguist/languages.yml

@@ -1,34 +1,35 @@
-# Defines all Languages known to GitHub.
+# Defines all languages known to GitHub.
 #
-# fs_name               - Optional field. Only necessary as a replacement for the sample directory name if the
-#                         language name is not a valid filename under the Windows filesystem (e.g., if it
-#                         contains an asterisk).
-# type                  - Either data, programming, markup, prose, or nil
-# aliases               - An Array of additional aliases (implicitly
-#                         includes name.downcase)
-# ace_mode              - A String name of the Ace Mode used for highlighting whenever
-#                         a file is edited. This must match one of the filenames in https://gh.io/acemodes.
-#                         Use "text" if a mode does not exist.
-# codemirror_mode       - A String name of the CodeMirror Mode used for highlighting whenever a file is edited.
-#                         This must match a mode from https://git.io/vi9Fx
-# codemirror_mime_type  - A String name of the file mime type used for highlighting whenever a file is edited.
-#                         This should match the `mime` associated with the mode from https://git.io/f4SoQ
-# wrap                  - Boolean wrap to enable line wrapping (default: false)
-# extensions            - An Array of associated extensions (the first one is
-#                         considered the primary extension, the others should be
-#                         listed alphabetically)
-# filenames             - An Array of filenames commonly associated with the language
-# interpreters          - An Array of associated interpreters
-# language_id           - Integer used as a language-name-independent indexed field so that we can rename
-#                         languages in Linguist without reindexing all the code on GitHub. Must not be
-#                         changed for existing languages without the explicit permission of GitHub staff.
-# color                 - CSS hex color to represent the language. Only used if type is "programming" or "markup".
-# tm_scope              - The TextMate scope that represents this programming
-#                         language. This should match one of the scopes listed in
-#                         the grammars.yml file. Use "none" if there is no grammar
-#                         for this language.
-# group                 - Name of the parent language. Languages in a group are counted
-#                         in the statistics as the parent language.
+# Required fields:
+#    type                  - Either "data", "programming", "markup" or "prose".
+#    ace_mode              - Ace mode used when editing files which use the language. This must match
+#                            one of the names in https://gh.io/acemodes. Use "text" if no mode exists.
+#    extensions            - List of associated file extensions, sorted in ascending ASCII order,
+#                            except for the language's primary extension, which is always listed first.
+#    filenames             - List of associated filenames, sorted in ascending ASCII order.
+#                            May be omitted if the extensions field is present (and vice versa).
+#    language_id           - Integer used as a language-name-independent indexed field so that we can rename
+#                            languages in Linguist without reindexing all the code on GitHub. Must not be
+#                            changed for existing languages without the explicit permission of GitHub staff.
+#    tm_scope              - The TextMate scope that represents this programming language.
+#                            This should match one of the scopes listed in grammars.yml.
+#                            Use "none" if there is no TextMate grammar for this language.
+#
+# Optional fields:
+#    aliases               - List of additional aliases (implicitly includes lowercased forms of language's name).
+#                            These are used in fenced code-blocks, code searches by language, and in overrides.
+#    codemirror_mode       - CodeMirror 5 mode used when editing files that use the language.
+#                            This must match one of the names listed here: https://git.io/vi9Fx
+#    codemirror_mime_type  - MIME media-type used by CodeMirror 5 for selecting a mode for editing the language.
+#                            The `mime` types supported by the named mode are listed here: https://git.io/f4SoQ
+#    color                 - CSS colour code used to represent the language (format: "#RRGGBB").
+#    fs_name               - Filesystem name used when creating directories for the language. Only necessary for
+#                            languages whose names contain symbols that are invalid or unsafe on certain systems.
+#    group                 - Name of the parent language. Languages in a group contribute to the usage statistics
+#                            of their parent language.
+#    interpreters          - List of programs that execute the language (by running and/or compiling it).
+#                            These are consulted when scrutinising a file's hashbang to determine its language.
+#    wrap                  - Enable soft line-wrapping (default: false)
 #
 # Any additions or modifications (even trivial) should have corresponding
 # test changes in `test/test_blob.rb`.