From abac27c0dd9f7efa50c03567a67b03f9877f474e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Emmanuel=20Beno=C3=AEt?= Date: Wed, 21 Oct 2020 13:50:45 +0200 Subject: [PATCH] Documentation - Introduction, installation, main configuration --- README.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..a2fa824 --- /dev/null +++ b/README.md @@ -0,0 +1,116 @@ +GPrompt - useless gimmicky prompt for Bash on Linux +==================================================== + +GPrompt (short for GadgetoPrompt) is a gimmicky Bash prompt generator +that displays sort-of-useful information. It only works on Linux because +that's what I use. It adapts to the terminal's width, showing or hiding +information depending on the conditions. + +## Features + +GPrompt prompts may consist in one or two lines. The top line is separated +in three areas (left, midddle and right), while the second line (the "input" +line, where the cursor is) only has a single, left-aligned area. Each area +may be configured to display information from one of the generators. In +addition, the script may be configured to generate a terminal title and/or +terminal icon title. + +## Installing GPrompt + +GPrompt may be installed either at the system level or on a per-user basis. + +### User installation + +* Copy the script and associated themes to your home directory. + + mkdir -p ~/.local/share/gprompt/themes + cp gprompt.pl ~/.local/share/gprompt + cp themes/* ~/.local/share/gprompt/themes + +* Add the following line to your `~/.bashrc`: + +`export PROMPT_COMMAND='eval "$($HOME/.local/share/gprompt/gprompt.pl $?)"'` + +### System-wide installation + +* In the case of a system-wide installation, the script and associated themes + must be copied to some shared location, e.g. + + mkdir -p /usr/share/gprompt/themes + cp -R gprompt.pl themes/ /usr/share/gprompt + +* Users may then use GPrompt by adding the following line to their `~/.bashrc` + files (it could also be added to `/etc/skel/.bashrc`) : + +`export PROMPT_COMMAND='eval "$(/usr/share/gprompt/gprompt.pl $?)"'` + +## Configuration + +GPrompt comes with a minimal (...-ish, this is a gadget after all) +configuration that will work out of the box. However, it can be customised +using both a system-wide configuration file and a per-user configuration file. +Values set in a configuration files override values that were previously +loaded, so it is possible to have a system-wide configuration that replaces +most of the defaults and a per-user configuration that only overrides a few of +the system-wide options. In addition, if the option is enabled from the +configuration files, it is possible to override settings using environment +variables. + +The GPrompt configuration is a Perl hash reference, so the general syntax of +the file goes something like this: + + { + 'some_key' => 'some_value' , + 'other_key' => [ 'list entry 1' , 'list entry 2' ] , + } + +In order to override a configuration entry using an environment variable, +the variable must be named `GPROMPT_` followed by the uppercase name of +the configuration entry. If the configuration expects a list for the +value in question, the value of the environment variable will be split using +the comma character. If a table is expected, keys and values are expected +to be separated by a colon. + + export GPROMPT_LAYOUT_RIGHT=git,load + export GPROMPT_LAYOUT_THEME_OVERRIDES=bg_left:230,bg_right:230 + +### Main configuration + +The following variables control the configuration itself: + +* `cfg_warn_files` indicates that the script should emit warnings when a file + (configuration or theme) cannot be loaded due to some error (`0` or `1`, + default `1`). +* `cfg_from_env` disables or enables configuration overrides from environment + variables (`0` or `1`, default `0`). +* `cfg_sys_themes` must list system-wide directories which may contain GPrompt + themes (list; default `/usr/share/gprompt/themes`). +* `cfg_user_themes` lists directories relative to the user's home which may + contain GPrompt themes (list; default `.local/share/gprompt/themes` and + `.gprompt-themes`). + +The `layout_*` variables control the prompt's layout and general appearance: + +* `layout_theme` is the name of the theme to use. The default theme will be used + if it contains an empty string. +* `layout_theme_overrides` may contain local overrides to the theme's contents + (table, empty by default). +* `layout_left`, `layout_middle`, `layout_right` and `layout_input` configure + the generators that will provide the contents of the top left, top center, + top right and bottom left sections of the prompt. All 4 variables are lists + of generator names; by default, the top bar is empty (the script does not + render it) and the input prompt only uses the `userhost` and `cwd` generators, + emulating a rather basic `\u@\h:\w` prompt. +* `layout_input_always` determines whether the input line should be rendered + even if no generators are specified (`0` or `1`, default `0`). + +The `term_*` variables control the prompt's ability to change the terminal's +title and/or icon title: + +* `term_set_title` controls whether the title or icon title of the terminal + should be changed. Possible values are `0` (no update), `1` (title), `2` + (icon title), and `3` (both). By default, only the title is updated. +* `term_generators` contains the list of generators that will produce the title + string (unicode characters in the generators' output will be removed). +* `term_separator` is a string that will be inserted between the various parts + of the string.