Merge pull request #26 from cafkafk/pr-1149

(exa PR) 1149: Created colors explanation file based on ogham's text

Justfile

@@ -100,6 +100,7 @@ all-release: build-release test-release
     mkdir -p "${CARGO_TARGET_DIR:-target}/man"
     pandoc --standalone -f markdown -t man man/eza.1.md        > "${CARGO_TARGET_DIR:-target}/man/eza.1"
     pandoc --standalone -f markdown -t man man/eza_colors.5.md > "${CARGO_TARGET_DIR:-target}/man/eza_colors.5"
+    pandoc --standalone -f markdown -t man man/eza_colors-explanation.5.md > "${CARGO_TARGET_DIR:-target}/man/eza_colors-explanation.5"
 
 # build and preview the main man page (eza.1)
 @man-1-preview: man
@@ -108,3 +109,7 @@ all-release: build-release test-release
 # build and preview the colour configuration man page (eza_colors.5)
 @man-5-preview: man
     man "${CARGO_TARGET_DIR:-target}/man/eza_colors.5"
+
+# build and preview the colour configuration man page (eza_colors.5)
+@man-5-explanations-preview: man
+    man "${CARGO_TARGET_DIR:-target}/man/eza_colors-explanation.5"

man/eza.1.md

@@ -243,7 +243,7 @@ See `https://no-color.org/` for details.
 
 Specifies the colour scheme used to highlight files based on their name and kind, as well as highlighting metadata and parts of the UI.
 
-For more information on the format of these environment variables, see the `eza_colors(5)` manual page.
+For more information on the format of these environment variables, see the [eza_colors.5.md](eza_colors.5.md) manual page.
 
 
 EXIT STATUSES
@@ -272,4 +272,5 @@ Our infinite thanks to Benjamin ‘ogham’ Sago and all the other contributors
 SEE ALSO
 ========
 
-- `eza_colors(5)`
+- [eza_colors.5.md](eza_colors.5.md)
+- [eza_colors-explanation.5.md](eza_colors-explanation.5.md)

man/eza_colors-explanation.5.md

@@ -0,0 +1,41 @@
+# Eza Color Explanation
+
+eza provides its own built\-in set of file extension mappings that cover a large range of common file extensions, including documents, archives, media, and temporary files.
+
+Any mappings in the environment variables will override this default set: running eza with `LS_COLORS="*.zip=32"` will turn zip files green but leave the colours of other compressed files alone.
+
+You can also disable this built\-in set entirely by including a
+`reset` entry at the beginning of `EXA_COLORS`.
+So setting `EXA_COLORS="reset:*.txt=31"` will highlight only text
+files; setting `EXA_COLORS="reset"` will highlight nothing.
+
+## Examples
+
+- Disable the "current user" highlighting: `EXA_COLORS="uu=0:gu=0"`
+- Turn the date column green: `EXA_COLORS="da=32"`
+- Highlight Vagrantfiles: `EXA_COLORS="Vagrantfile=1;4;33"`
+- Override the existing zip colour: `EXA_COLORS="*.zip=38;5;125"`
+- Markdown files a shade of green, log files a shade of grey:
+`EXA_COLORS="*.md=38;5;121:*.log=38;5;248"`
+
+## BUILT\-IN EXTENSIONS
+
+"Immediate" files are the files you should look at when downloading and building a project for the first time: READMEs, Makefiles, Cargo.toml, and others.
+They are highlighted in _yellow_ and _underlined_.
+
+- Images (png, jpeg, gif) are purple.
+- Videos (mp4, ogv, m2ts) are a slightly purpler purple.
+- Music (mp3, m4a, ogg) is a deeper purple.
+- Lossless music (flac, alac, wav) is deeper than *that* purple. In general, most media files are some shade of purple.
+- Cryptographic files (asc, enc, p12) are a faint blue.
+- Documents (pdf, doc, dvi) are a less faint blue.
+- Compressed files (zip, tgz, Z) are red.
+- Temporary files (tmp, swp, ~) are grey.
+- Compiled files (class, o, pyc) are faint orange. A file is also counted as compiled if it uses a common extension and is
+in the same directory as one of its source files: styles.css will count as compiled when next to styles.less or styles.sass, and scripts.js when next to scripts.ts or scripts.coffee.
+
+
+## See also
+
+- [eza.1.md](eza.1.md)
+- [eza_colors.5.md](eza_colors.5.md)

man/eza_colors.5.md

@@ -280,4 +280,5 @@ Our infinite thanks to Benjamin ‘ogham’ Sago and all the other contributors
 SEE ALSO
 ========
 
-- `eza(1)`
+- [eza.1.md](eza.1.md)
+- [eza_colors-explanation.5.md](eza_colors-explanation.5.md)