From 0aa7d646a71578e397eb0fb12adf32d0086d88d1 Mon Sep 17 00:00:00 2001 From: Linus Dierheimer Date: Mon, 9 Jan 2023 15:20:30 +0100 Subject: [PATCH] Initial logo documentation --- README.md | 27 ++----------- doc/logo.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 115 insertions(+), 24 deletions(-) create mode 100644 doc/logo.md diff --git a/README.md b/README.md index 8bce6372b..0957e7ec6 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ At the moment the performance difference is measurable, but too small to be huma There are some premade config files in [`presets`](presets), including the ones used for the screenshots above. You can load them using `--load-config `. They may also serve as a good example for format arguments. +Logos can be heavily customized to. See the [logo documentation](doc/logo.md) for more information. + ## Dependencies Fastfetch dynamically loads needed libraries if they are available. On Linux, its only hard dependencies are `libc` (any implementation of the c standard library), `libdl` and [`libpthread`](https://man7.org/linux/man-pages/man7/pthreads.7.html) (if built with multithreading support). They are all shipped with [`glibc`](https://www.gnu.org/software/libc/), which is already installed on most linux distributions. @@ -88,33 +90,10 @@ All categories not listed here should work without needing a specific implementa Title, Separator, OS, Host, Bios, Board, Kernel, Uptime, Processes, Packages, Shell, Resolution, DE, WM, WMTheme, Theme, Icons, Font, Cursor, Terminal, Terminal Font, CPU, CPUUsage, GPU, Memory, Swap, Disk, Battery, Power Adapter, Player, Media, Vulkan, OpenGL, OpenCL, LocalIP, PublicIP, Wifi, DateTime, Date, Time, Locale, Colors, Break, Custom ``` -##### Logos +##### Builtin logos ``` AlmaLinux, Alpine, Android, Arch, Arco, Artix, Bedrock, CachyOS, CentOS, CRUX, Crystal, Debian, Devuan, Deepin, Endeavour, Enso, Fedora, FreeBSD, Garuda, Gentoo, KDE Neon, KISS, Kubuntu, LangitKetujuh, Linux, MacOS, Manjaro, Mint, MSYS2, NixOS, Nobara, OpenSUSE, OpenSUSE Tumbleweed, OpenSUSE LEAP, Parabola, Raspbian, Pop!_OS, RebornOS, RedstarOS, Rocky, Rosa, Slackware, Solus, Ubuntu, Vanilla, Void, Windows 11, Windows 8, Windows, Zorin ``` -* Most of the logos have a small variant. Access it by appending _small to the logo name. -* Some logos have an old variant. Access it by appending _old to the logo name. -* To disable the logo, use `--logo none`. -* Get a list of all available logos with `fastfetch --print-logos`. - -###### Image logo - -Printing images as logo is supported using Sixel / Kitty / iTerm graphics protocol or chafas image to text conversion. - -* Sixel: fastfetch must be built with imagemagick support to convert image to sixel format -* Kitty: Because [kitty support png](https://sw.kovidgoyal.net/kitty/graphics-protocol/#png-data) natively, using `png` image file with both `--logo-width` and `--logo-height` being specified is recommanded to get maximum performance. Otherwise, imagemagick is required to convert image to RGBA data. -* iTerm: [Since iTerm supports a lot of image format](https://iterm2.com/documentation-images.html), imagemagick support is not required. However, both `--logo-width` and `--logo-height` must be specified since fastfetch has no idea about the size of the image. -* Chafa: Requires imagemagick support. -* Raw: use a pre-converted image file so that fastfetch don't need to convert the image format on the fly. -```shell -# brew install libsixel -$ img2sixel image.png -o image.sixel -$ fastfetch --raw image.sixel --logo-width 30 --logo-height 15 - -# wget https://iterm2.com/utilities/imgcat && chmod +x imgcat -$ imgcat image.png > image.raw -$ fastfetch --raw image.raw --logo-width 30 --logo-height 15 -``` ##### Package managers ``` diff --git a/doc/logo.md b/doc/logo.md new file mode 100644 index 000000000..c24cae948 --- /dev/null +++ b/doc/logo.md @@ -0,0 +1,112 @@ +# Logo Documentation + +## Logo options + +### General + +| Option | Default | Description | +|--------|---------|-------------| +| `--logo`, `-l` | `""` | The logo source, interpreted depending on type | +| `--logo-type` | `auto` | The logo type. See the following categories for possible values | +| `--` | `""` | Short for `--logo-type --logo ` | +| `--logo-padding` | `""` | Sets the padding left and right of the logo | +| `--logo-padding-left` | `0` | Sets the padding left of the logo | +| `--logo-padding-right` | `4` | Sets the padding right of the logo | +| `--logo-padding-top` | `0` | Sets the padding top of the logo | + +### Text + +| Option | Default | Description | +|--------|---------|-------------| +| `--logo-color-[1-9]` | `""` | Overrides a color for logos that support it | +| `--logo-print-remaining` | `true` | Print the remaining logo, if it is higher than the keys | + +* Color placeholders are in the form `$[1-9]`. To print a `$`, use `$$`. +* If a color placeholder value is not set, the placeholder is simply discarded. + +### Image + +| Option | Default | Description | +|--------|---------|-------------| +| `--logo-width` | `""` | Sets the width of the logo for logos that support it | +| `--logo-height` | `""` | Sets the height of the logo for logos that support it | + +* If one of the height / width options is set, but the other not, the aspect ratio is preserved. +* If neither height nor width is set, the original size is used. + +## Logo types + +### auto + +Trys to detect the logo type depending on the value of `--logo`, in the following order: +* If the value is empty / not set, an autodected builtin logo is displayed. +* If the value is the name of a builtin logo, it is displayed. +* If the value is the path to an image file, and the terminal emulator is known to support an image protocol, the image is displayed. +* If the value is the path to a text file, the content is displayed. +* The autodetected builtin logo is displayed. + +### builtin + +The value of `--logo` is interpreted as the name of a builtin logo. +* If the value is empty / not set, it is autodetected. +* Use `--list-logos` to get a list of all available logos. +* Use `--print-logos` to see all available logos. +* All builtin logos set default values for `--logo-color-[1-9]`. +* Use `none` to disable the logo, but keep key colors from the detected logo. + +### file + +The value of `--logo` is interpreted as the path to a file. The content of the file is displayed. +* If the file can't be read, the autodetected builtin logo is displayed. + +### file-raw + +The value of `--logo` is interpreted as the path to a file. The content of the file is displayed. +* No color placeholder replacement is done. +* If the file can't be read, the autodetected builtin logo is displayed. + +### data + +The value of `--logo` is interpreted as the logo and directly displayed. +* If the value is empty / not set, the autodetected builtin logo is displayed. + +### data-raw + +The value of `--logo` is interpreted as the logo and directly displayed. +* No color placeholder replacement is done. +* If the value is empty / not set, the autodetected builtin logo is displayed. + +### sixel + +The value of `--logo` is interpreted as the path to an image file. It is displayed using the sixel graphics protocol. +* `fastfetch` must be compiled with the `imagemagick6` or `imagemagick7` feature. + +### kitty + +The value of `--logo` is interpreted as the path to an image file. It is displayed using the kitty graphics protocol. +* If the file is a png file, and both `--logo-width` and `--logo-height` are specified, the image is directly send to the terminal emulator. +* Otherwise `fastfetch` must be compiled with the `imagemagick6` or `imagemagick7` feature. + +### iterm + +The value of `--logo` is interpreted as the path to an image file. It is displayed using the iTerm graphics protocol. +* Both `--logo-width` and `--logo-height` must be specified. + +### chafa + +The value of `--logo` is interpreted as the path to an image file. It is converted to an ascii logo using `libchafa`. +* `fastfetch` must be compiled with the `chafa` feature. +* `fastfetch` must be compiled with the `imagemagick6` or `imagemagick7` feature. +* Use `--chafa-fg-only` to set weather to render foreground only. +* Use `--chafa-symbols` to set the symbols. +* Use `--chafa-canvas-mode` to set the canvas mode. +* Use `--chafa-color-space` to set the color space. +* Use `--chafa-dither-mode` to set the dither mode. +* See the [chafa documentation](https://hpjansson.org/chafa/man/) for more information. + +### raw + +The value of `--logo` is interpreted as the path to a binary file. It is printed as-is. +* Both `--logo-width` and `--logo-height` must be specified. +* Use this to display a pre converted image file. +* If the file can't be read, the autodetected builtin logo is displayed.