Merge pull request #459 from dylanaraps/config_rewrite

Config: Rewrite docs

config/config

@@ -7,7 +7,6 @@
 export LC_ALL=C
 export LANG=C
 
-
 # See this wiki page for more info:
 # https://github.com/dylanaraps/neofetch/wiki/Customizing-Info
 print_info() {
@@ -51,8 +50,15 @@ print_info() {
 # Kernel
 
 
-# Shorten the output of the kernel function
+# Shorten the output of the kernel function.
-# --kernel_shorthand on, off
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --kernel_shorthand
+#
+# Example:
+# on:  '4.8.9-1-ARCH'
+# off: 'Linux 4.8.9-1-ARCH'
 kernel_shorthand="on"
 
 
@@ -60,12 +66,23 @@ kernel_shorthand="on"
 
 
 # Shorten the output of the distro function
-# NOTE: This is only possible on Linux, macOS, and Solaris
+#
-# --distro_shorthand on, off, tiny
+# Default:  'off'
+# Values:   'on', 'off', 'tiny'
+# Flag:     --distro_shorthand
+# Supports: Linux, macOS, and Solaris.
 distro_shorthand="off"
 
-# Show 'x86_64' and 'x86' in 'Distro:' output.
+# Show/Hide OS Architecture.
-# --os_arch on, off
+# Show 'x86_64', 'x86' and etc in 'Distro:' output.
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --os_arch
+#
+# Example:
+# on:  'Arch Linux x86_64'
+# off: 'Arch Linux'
 os_arch="on"
 
 
@@ -73,7 +90,15 @@ os_arch="on"
 
 
 # Shorten the output of the uptime function
-# --uptime_shorthand tiny, on, off
+#
+# Default: 'off'
+# Values:  'on', 'off', 'tiny'
+# Flag:    --uptime_shorthand
+#
+# Example:
+# on:   '2 days, 10 hours, 3 mins'
+# off:  '2 days, 10 hours, 3 minutes'
+# tiny: '2d 10h 3m'
 uptime_shorthand="off"
 
 
@@ -81,11 +106,25 @@ uptime_shorthand="off"
 
 
 # Show the path to $SHELL
-# --shell_path on, off
+#
+# Default: 'off'
+# Values:  'on', 'off'
+# Flag:    --shell_path
+#
+# Example:
+# on:  '/bin/bash'
+# off: 'bash'
 shell_path="off"
 
 # Show $SHELL version
-# --shell_version on, off
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --shell_version
+#
+# Example:
+# on:  'bash 4.4.5'
+# off: 'bash'
 shell_version="on"
 
 
@@ -93,37 +132,62 @@ shell_version="on"
 
 
 # CPU speed type
-# Only works on Linux with cpufreq.
+#
-# --speed_type current, min, max, bios,
+# Default: 'max'
-# scaling_current, scaling_min, scaling_max
+# Values:  'current', 'min', 'max', 'bios',
+#          'scaling_current', 'scaling_min',
+#          'scaling_max'
+# Flag:    --speed_type
+# Supports: Linux with 'cpufreq'
 speed_type="max"
 
 # Shorten the output of the CPU function
-# --cpu_shorthand name, speed, tiny, on, off
+#
+# Default: 'off'
+# Values:  'on', 'off', 'tiny', 'name', 'speed'
+# Flag:    --cpu_shorthand
+#
+# Example:
+# on:    'i7-6500U (4) @ 3.1GHz'
+# off:   'Intel i7-6500U (4) @ 3.1GHz'
+# tiny:  'i7-6500U (4)'
+# name:  'Intel i7-6500U (4)'
+# speed: '3.1GHz'
 cpu_shorthand="off"
 
-# CPU Usage display
-# Set CPU usage display setting
-# --cpu_display bar, infobar, barinfo, off
-cpu_display="off"
-
 # CPU Speed
 # Hide/Show CPU speed.
-# --cpu_speed on, off
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --cpu_speed
+#
+# Example:
+# on:  'Intel i7-6500U (4) @ 3.1GHz'
+# off: 'Intel i7-6500U (4)'
 cpu_speed="on"
 
 # CPU Cores
 # Display CPU cores in output
-# Logical: All virtual cores
+#
-# Physical: All physical cores
+# Default: 'logical'
-# Note: 'physical' doesn't work on BSD.
+# Values:  'logical', 'physical', 'off'
-# --cpu_cores logical, physical, off
+# Flag:    --cpu_cores
+# Support: 'physical' doesn't work on BSD.
+#
+# Example:
+# logical:  'Intel i7-6500U (4) @ 3.1GHz' (All virtual cores)
+# physical: 'Intel i7-6500U (2) @ 3.1GHz' (All physical cores)
+# off:      'Intel i7-6500U @ 3.1GHz'
 cpu_cores="logical"
 
 # CPU Temperature
 # Hide/Show CPU temperature.
-# Note: Only works on Linux.
+#
-# --cpu_temp on, off
+# Default: 'off'
+# Values:  'on', 'off'
+# Flag:    --cpu_temp
+# Supports: Linux
 cpu_temp="off"
 
 
@@ -131,7 +195,14 @@ cpu_temp="off"
 
 
 # Enable/Disable GPU Brand
-# --gpu_brand on, off
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --gpu_brand
+#
+# Example:
+# on:  'AMD HD 7950'
+# off: 'HD 7950'
 gpu_brand="on"
 
 
@@ -139,25 +210,52 @@ gpu_brand="on"
 
 
 # Display refresh rate next to each monitor
-# Unsupported on Windows
+# Default: 'off'
-# --refresh_rate on, off
+# Values:  'on', 'off'
+# Flag:    --refresh_rate
+# Supports: Doesn't work on Windows.
+#
+# Example:
+# on:  '1920x1080 @ 60Hz'
+# off: '1920x1080'
 refresh_rate="off"
 
 
-# Gtk Theme / Icons
+# Gtk Theme / Icons / Font
 
 
-# Shorten output (Hide [GTK2] etc)
+# Shorten output of GTK Theme / Icons / Font
-# --gtk_shorthand on, off
+#
+# Default: 'off'
+# Values:  'on', 'off'
+# Flag:    --gtk_shorthand
+#
+# Example:
+# on:  'Numix, Adwaita'
+# off: 'Numix [GTK2], Adwaita [GTK3]'
 gtk_shorthand="off"
 
 
-# Enable/Disable gtk2 theme/icons output
+# Enable/Disable gtk2 Theme / Icons / Font
-# --gtk2 on, off
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --gtk2
+#
+# Example:
+# on:  'Numix [GTK2], Adwaita [GTK3]'
+# off: 'Adwaita [GTK3]'
 gtk2="on"
 
-# Enable/Disable gtk3 theme/icons output
+# Enable/Disable gtk3 Theme / Icons / Font
-# --gtk3 on, off
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --gtk3
+#
+# Example:
+# on:  'Numix [GTK2], Adwaita [GTK3]'
+# off: 'Numix [GTK2]'
 gtk3="on"
 
 
@@ -165,7 +263,10 @@ gtk3="on"
 
 
 # Website to ping for the public IP
-# --ip_host url
+#
+# Default: 'http://ident.me'
+# Values:  'url'
+# Flag:    --ip_host
 public_ip_host="http://ident.me"
 
 
@@ -173,25 +274,50 @@ public_ip_host="http://ident.me"
 
 
 # Print the Artist and Title on seperate lines
-# --song_shorthand on, off
+#
+# Default: 'off'
+# Values:  'on', 'off'
+# Flag:    --song_shorthand
+#
+# Example:
+# on:  'Artist: The Fratellis'
+#      'Song: Chelsea Dagger'
+#
+# off: 'Song: The Fratellis - Chelsea Dagger'
 song_shorthand="off"
 
 
 # Birthday
 
 
-# Whether to show a long pretty output
+# Shorten the output of the Birthday functon.
-# or a shortened one
+#
-# NOTE: Long pretty output doesn't work on OpenBSD or NetBSD.
+# Default:  'off'
-# --birthday_shorthand on, off
+# Values:   'on', 'off'
+# Flag:     --birthday_shorthand
+# Supports: 'off' doesn't work on OpenBSD and NetBSD.
+#
+# Example:
+# on:  'Thu 14 Apr 2016 11:50 PM'
+# off: '2016-04-14 23:50:55'
 birthday_shorthand="off"
 
 # Whether to show the time in the output
-# --birthday_time on, off
+#
+# Default:  'on'
+# Values:   'on', 'off'
+# Flag:     --birthday_time
+#
+# Example:
+# on:  'Thu 14 Apr 2016 11:50 PM'
+# off: 'Thu 14 Apr 2016'
 birthday_time="on"
 
 # Date format to use when printing birthday
-# --birthday_format "format"
+#
+# Default:  '+%a %d %b %Y %l:%M %p'
+# Values:   'date format'
+# Flag:     --birthday_format
 birthday_format="+%a %d %b %Y %l:%M %p"
 
 
@@ -199,12 +325,17 @@ birthday_format="+%a %d %b %Y %l:%M %p"
 
 
 # Text Colors
-# Each number represents a different part of
+#
-# the text in this order:
+# Default:  'distro'
-# title, @, underline, subtitle, colon, info
+# Values:   'distro', 'num' 'num' 'num' 'num' 'num' 'num'
-# colors=(4 6 1 8 8 6)
+# Flag:     --colors
-# You can also specify:
+#
-# fg (foreground color)
+# Each number represents a different part of the text in
+# this order: 'title', '@', 'underline', 'subtitle', 'colon', 'info'
+#
+# Example:
+# colors=(distro)      - Text is colored based on Distro colors.
+# colors=(4 6 1 8 8 6) - Text is colored in the order above.
 colors=(distro)
 
 
@@ -212,15 +343,24 @@ colors=(distro)
 
 
 # Toggle bold text
-# --bold on, off
+#
+# Default:  'on'
+# Values:   'on', 'off'
+# Flag:     --bold
 bold="on"
 
 # Enable/Disable Underline
-# --underline on, off
+#
+# Default:  'on'
+# Values:   'on', 'off'
+# Flag:     --underline
 underline_enabled="on"
 
 # Underline character
-# --underline_char char
+#
+# Default:  '-'
+# Values:   'string'
+# Flag:     --underline_char
 underline_char="-"
 
 
@@ -228,56 +368,105 @@ underline_char="-"
 
 
 # Color block range
-# --block_range start end
+# Start/End refer to the range of colors
+# to print in the blocks.
+#
+# Default:  '0', '7'
+# Values:   'num'
+# Flag:     --block_range
+#
+# Example:
+#
+# Display colors 0-7 in the blocks.
+# neofetch --block_range 0 7
+#
+# Display colors 0-15 in the blocks.
+# neofetch --block_range 0 15
 start=0
 end=7
 
 # Toggle color blocks
-# --color_blocks on, off
+#
+# Default:  'on'
+# Values:   'on', 'off'
+# Flag:     --color_blocks
 color_blocks="on"
 
 # Color block width in spaces
-# --block_width num
+#
+# Default:  '3'
+# Values:   'num'
+# Flag:     --block_width
 block_width=3
 
 # Color block height in lines
-# --block_height num
+#
+# Default:  '1'
+# Values:   'num'
+# Flag:     --block_height
 block_height=1
 
 
 # Progress Bars
 
 
-# Progress bar character
+# Bar characters
-# --progress_char elapsed_char total_char
+#
+# Default:  '-', '='
+# Values:   'string', 'string'
+# Flag:     --bar_char
+#
+# Example:
+# neofetch --bar_char 'elapsed' 'total'
+# neofetch --bar_char '-' '='
 bar_char_elapsed="-"
 bar_char_total="="
 
-# Progress border
+# Toggle Bar border
-# --progress_border on, off
+#
+# Default:  'on'
+# Values:   'on', 'off'
+# Flag:     --bar_border
 bar_border="on"
 
 # Progress bar length in spaces
 # Number of chars long to make the progress bars.
-# --progress_length num
+#
-bar_length="15"
+# Default:  '15'
+# Values:   'num'
+# Flag:     --bar_length
+bar_length=15
 
 # Progress bar colors
-# When set to distro, uses your distro's logo colors
+# When set to distro, uses your distro's logo colors.
-# Takes: num, "distro"
+#
-# --progress_colors col col
+# Default:  'distro', 'distro'
+# Values:   'distro', 'num'
+# Flag:     --bar_colors
+#
+# Example:
+# neofetch --bar_colors 3 4
+# neofetch --bar_colors distro 5
 bar_color_elapsed="distro"
 bar_color_total="distro"
 
-# Customize how the info is displayed.
+
-# bar: Only the progress bar is displayed.
+# Info display
-# infobar: The bar is displayed after the info.
+# Display a bar with the info.
-# barinfo: The bar is displayed before the info.
-# off: Only the info is displayed.
 #
-# --memory_display bar, infobar, barinfo, off
+# Default: 'off'
-# --battery_display bar, infobar, barinfo, off
+# Values:  'bar', 'infobar', 'barinfo', 'off'
-# --disk_display bar, infobar, barinfo, off
+# Flags:   --cpu_display
+#          --memory_display
+#          --battery_display
+#          --disk_display
+#
+# Example:
+# bar:     '[---=======]'
+# infobar: 'info [---=======]'
+# barinfo: '[---=======] info'
+# off:     'info'
+cpu_display="off"
 memory_display="off"
 battery_display="off"
 disk_display="off"
@@ -287,16 +476,22 @@ disk_display="off"
 
 
 # Image Source
-# --image wallpaper, /path/to/img, /path/to/dir/, off
+#
+# Default:  'wallpaper'
+# Values:   'wallpaper', '/path/to/img', '/path/to/dir/', 'off'
+# Flag:     --image
 image_source="wallpaper"
 
 # Thumbnail directory
+#
+# Default: '~/.cache/thumbnails/neofetch'
+# Values:  'dir'
 thumbnail_dir="${XDG_CACHE_HOME:-${HOME}/.cache}/thumbnails/neofetch"
 
-# W3m-img path
+# w3m-img path
 # Only works with the w3m backend.
 #
-# NOTE: Only change this if "neofetch -v" says that it couldn't find w3m-img.
+# NOTE: Only change this if "neofetch -v" says that it "couldn't find w3m-img".
 # Neofetch has a function that automatically finds w3m-img for you. It looks
 # in the following directories:
 #    /usr/lib/w3m/w3mimgdisplay
@@ -310,35 +505,56 @@ thumbnail_dir="${XDG_CACHE_HOME:-${HOME}/.cache}/thumbnails/neofetch"
 w3m_img_path="/usr/lib/w3m/w3mimgdisplay"
 
 # Crop mode
-# --crop_mode normal, fit, fill
+#
+# Default:  'normal'
+# Values:   'normal', 'fit', 'fill'
+# Flag:     --crop_mode
+#
+# See this wiki page to learn about the fit and fill options.
+# https://github.com/dylanaraps/neofetch/wiki/What-is-Waifu-Crop%3F
 crop_mode="normal"
 
 # Crop offset
-# Only affects normal mode.
+# Note: Only affects 'normal' crop mode.
-# --crop_offset northwest, north, northeast, west, center
+#
-#               east, southwest, south, southeast
+# Default:  'center'
+# Values:   'northwest', 'north', 'northeast', 'west', 'center'
+#           'east', 'southwest', 'south', 'southeast'
+# Flag:     --crop_offset
 crop_offset="center"
 
 # Image size
 # The image is half the terminal width by default.
-# --size auto, 00px, 00%, none
+#
+# Default: 'auto'
+# Values:  'auto', '00px', '00%', 'none'
+# Flags:   --image_size
+#          --size
 image_size="auto"
 
-# Right gap between image and text
+# Ggap between image and text
-# --gap num
+#
+# Default: '3'
+# Values:  'num', '-num'
+# Flag:    --gap
 gap=3
 
 # Image offsets
 # Only works with the w3m backend.
-# --xoffset px
+#
-# --yoffset px
+# Default: '0'
+# Values:  'px'
+# Flags:   --xoffset
+#          --yoffset
 yoffset=0
 xoffset=0
 
 # Image background color
 # Only works with the w3m backend.
-# Unset by default.
+#
-# --bg_color 'color', blue
+# Default: ''
+# Values:  'color', 'blue'
+# Flag:    --bg_color
 background_color=
 
 
@@ -348,33 +564,47 @@ background_color=
 # Default ascii image to use
 # When this is set to distro it will use your
 # distro's logo as the ascii.
-# --ascii 'distro', path/to/ascii
+#
+# Default: 'distro'
+# Values:  'distro', '/path/to/ascii_file'
+# Flag:    --ascii
 ascii="distro"
 
 # Ascii distro
 # Which distro's ascii art to display.
-# --ascii_distro 'auto', 'distro_name'
+#
+# Default: 'auto'
+# Values:  'auto', 'distro_name'
+# Flag:    --ascii_distro
 ascii_distro="auto"
 
-# Ascii colors
+# Ascii Colors
-# When this is set to distro it will use your
+#
-# ditro's colors to color the ascii.
+# Default:  'distro'
-# NOTE: You can also set this to a range of colors
+# Values:   'distro', 'num' 'num' 'num' 'num' 'num' 'num'
-# which will allow you to custom color distro logos
+# Flag:     --ascii_colors
-# --ascii_colors distro
+#
-# --ascii_colors 2 4 5 6
+# Example:
+# ascii_colors=(distro)      - Ascii is colored based on Distro colors.
+# ascii_colors=(4 6 1 8 8 6) - Ascii is colored using these colors.
 ascii_colors=(distro)
 
 # Logo size
 # Arch, Crux and Gentoo have a smaller logo
 # variant. Changing the value below to small
 # will make neofetch use the small logo.
-# --ascii_logo_size small, normal
+#
+# Default: 'normal'
+# Values:  'normal', 'small'
+# Flag:    --ascii_logo_size
 ascii_logo_size="normal"
 
 # Bold ascii logo
 # Whether or not to bold the ascii logo.
-# --ascii_bold on, off
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --ascii_bold
 ascii_bold="on"
 
 
@@ -383,25 +613,46 @@ ascii_bold="on"
 
 # Whether or not to always take a screenshot
 # You can manually take a screenshot with "--scrot" or "-s"
+#
+# Default: 'off'
+# Values:  'on', 'off'
+# Flags:   --scrot
+#          -s
 scrot="off"
 
 # Screenshot program to launch
-# --scrot_cmd
+# If you're not using 'scrot' change this to your screenshot
+# program.
+#
+# Default: 'scrot -c -d 3'
+# Values:  'cmd -flags'
+# Flag:    --scrot_cmd
 scrot_cmd="scrot -c -d 3"
 
 # Scrot dir
 # Where to save the screenshots
-# --scrot_dir /path/to/screenshot/folder
+#
+# Default: '~/Pictures/'
+# Values:  'dir'
+# Flag:    --scrot_dir
+#
+# Note: Neofetch won't create the directory if it doesn't exist.
 scrot_dir="$HOME/Pictures/"
 
 # Scrot filename
 # What to name the screenshots
-# --scrot_name str
+#
+# Default: 'neofetch-$(date +%F-%I-%M-%S-${RANDOM}).png'
+# Values:  'string'
+# Flag:    --scrot_name
 scrot_name="neofetch-$(date +%F-%I-%M-%S-${RANDOM}).png"
 
 # Image upload host
 # Where to upload the image.
-# Possible values: imgur, teknik
+#
+# Default: 'imgur'
+# Values:  'imgur', 'teknik'
+# Flag:    --image_host
 image_host="imgur"
 
 
@@ -409,9 +660,24 @@ image_host="imgur"
 
 
 # Enable/Disable config file
+#
+# Default: 'on'
+# Values:  'on', 'off'
+# Flag:    --config
 # --config off, none
+#
+# Note: This option is only used when neofetch sources this config
+# as a default config and NOT as a user config. Changing this in
+# your user config won't actually do anything.
 config="on"
 
 # Path to custom config file location
-# --config path/to/config
+#
+# Default: '${XDG_CONFIG_HOME:-${HOME}/.config}/neofetch/config'
+# Values:  '/path/to/config'
+# Flag:    --config_file
+#
+# Note: This option is only used when neofetch sources this config
+# as a default config and NOT as a user config. Changing this in
+# your user config won't actually do anything.
 config_file="${XDG_CONFIG_HOME:-${HOME}/.config}/neofetch/config"