diff --git a/README.md b/README.md new file mode 100644 index 0000000..9cf3720 --- /dev/null +++ b/README.md @@ -0,0 +1,435 @@ +DotMatrix — A Liquid Prompt Theme +================================= + +Neon is a theme for [Liquid Prompt](https://github.com/nojhan/liquidprompt). + +It is an original prompt design, very carefully designed, +that will completely changes the way you imagine the prompt. + +It is focused on *improving the user experience*, +by vastly improving the ability of the user to immediatly spot +what she should do following her system's state changes. + +Has such, you may find it a little bit disconcerting at first. +But we believe that the advantages of this design makes it worth the effort. + + +Preview +------- + +If there is nothing special about the current context, the appearance of +DotMatrix might be as simple as this: + +![](dotmatrix-short-chevron.png) + +A typical display of a slightly complex session would look like this: + +![](dotmatrix-med-chevron.png) + +The DotMatrix theme also comes as several variants, changing the shape of the segments separators, +like the (default) "dotmatrix" pixels: + +![](dotmatrix-short-dots.png) + +or the "slant" variant: + +![](dotmatrix-med-slant.png) + + +Design +------ + +### Rationale + +The DotMatrix theme use a couple of design principles: + +* It is accessible to colorblind people, hence it uses: + * only four colors: dark grey, white, blue and yellow. + * At least a text item for each segment, + * or a blank space between segments. +* The blue colors means that the user is probably expected to perform some task. +* The yellow color carries an error or something of concern. +* Segments for "default" state are joined with graphical symbols that reads from right to left, + in a way that makes sense. +* It uses three ways to carry information about the state of the system: + * Important states are denoted by text. + * Ancillary states can be shown with a single character/icon. + * States appearing from a user action can be shown by "detaching" two segments usually joined. + When possible, this added space is shown as having a right-to-left direction. + +The prompt itself is designed in three lines: + +- The first line shows the state of the shell itself (type of graphical server, remote connection, user, host, path, etc.) on the left, + and optional sensors states on the right (temperature, jobs, time, etc.). +- The second line displays whatever keywords have a meaning in the context (virtual environments, software collections, etc.). +- The third line indicates the relationships toward extern services (internet, VCS) and immediate status (runtime, error code). + This is also where the actual prompt is. + + +### Example + +For instance, in the following prompt, you can see that the user is in a Git repository and has some action waiting to be done: +- the rightmost blue "≠" indicates that there are some modifications waiting to be commited (hence the directional hint, from a diff to the branch). +- the leftmost blue segment indicates that there are some commits that may be pushed to the remote (hence the directional hint, from the branch to the VCS symbol). + +![](dotmatrix-intro-chevron.png) + +The screenshot also shows that the last command ended in an error, hence the red-over-yellow error code. + +The upper section shows a classical state of the prompt: a shell within a graphical server ("X"), +for the default login user ("", a figure), on localhost ("", an island), in the liquidprompt directory, which is underlined because it is also a VCS repository. + + +### Full description + +The following diagram shows almost all the possible states of a DotMatrix Liquid Prompt: + +![](liquidprompt_dotmatrix_design.svg) + + +Setup +----- + +To actually use the DotMatrix theme, you need to add a few configuration commands to the script that loads Liquid Prompt. +For example: + +```sh + + # Load Liquid Prompt. + source ~/.liquidprompt + # Configure the desired variant. + DOTMATRIX_VARIANT="chevron" + # Load the theme. + source ~/code/liquidprompt/themes/dotmatrix/dotmatrix.theme && lp_theme dotmatrix +``` + +NOTE: The recommended segment markers (the "chevron" variant) uses characters in the private section of unicode +that are defined by the "Nerd-fonts" project. +You will either need a compatible font, or use a variant that does not need them, like "text" and "dotmatrix". + +See the [Nerd-fonts Fonts installation docs](https://www.nerdfonts.com) for help on installing this kind of fonts. + + +Variants +-------- + +Variants needing a Nerd-fonts font: + +- "chevron" (the recommended one): + +![](dotmatrix-short-chevron.png) + +- "round": + +![](dotmatrix-short-round.png) + +- "slant": + +![](dotmatrix-short-slant.png) + +Variants available with a regular font: + +- "dotmatrix" (the default): + +![](dotmatrix-short-dots.png) + +- "text" (using only common characters): + +![](dotmatrix-short-text.png) + + +Configuration +------------- + +### Liquid Prompt Configuration + +The DotMatrix theme honors Liquid Prompt configuration options, +except for the ones defining colors, specific marks and disabling some features. + +The following options are honored: + +- [`LP_ENABLE_PERM`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_ENABLE_PERM), +- [`LP_ENABLE_VCS_DIFFSTATS`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_ENABLE_VCS_DIFFSTATS), +- [`LP_ENABLE_UNCOMMITED`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_ENABLE_UNCOMMITED), +- [`LP_MARK_BATTERY`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_MARK_BATTERY), +- [`LP_MARK_LOAD`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_MARK_LOAD), +- [`LP_MARK_TEMP`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_MARK_TEMP), +- [`LP_PS1_PREFIX`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_PS1_PREFIX). + +The following options are **not honored**: + +- every ``LP_COLOR_\*`` options. +- all the others ``LP_MARK_\*`` options not listed in the above section. +- [`LP_USER_ALWAYS`](https://liquidprompt.readthedocs.io/en/stable/config.html#LP_USER_ALWAYS) (at least a user icon is always displayed). + + +### Theme Configuration + +#### High-level + +**DOTMATRIX_VARIANT** *string = "dotmatrix"* + +The variant of the theme. +This mainly change the segments separation style, +but can also impact the icons on some variants. + +Allowed values: + +- "dotmatrix" (the *default*), +- "chevron" (the *recommended*, need a Nerd-fonts font), +- "slant" (need a Nerd-fonts font), +- "round" (need a Nerd-fonts font), +- "text" (the one that works anywhere). + + +**DOTMATRIX_SPACED** *boolean = 1* + +If set to false, this flag will configure a compact prompt, +showing segments without extra spaces around their joints. + +Example of a spaced prompt: + +![](dotmatrix-spaced.png) + +Example of a compact prompt: + +![](dotmatrix-unspaced.png) + + +#### Generic Markers + +The following options configure some marks that will be used across all variants of the theme. + +**DOTMATRIX_DISPLAY_TEXT** *string = "T"* + +The marker used to indicates that the shell is in text mode, +i.e. that does not have a graphical display +(more rigorously: there is no X11 :envvar:`DISPLAY` environment variable). + + +**DOTMATRIX_DISPLAY_X11** *string = "X"* + +The marker used to indicates that the shell does have access to a graphical server +(more rigorously: there is a X11 :envvar:`DISPLAY` environment variable). + + +**DOTMATRIX_HOST_LOCAL** *string = "⌂"* + +The marker used to indicate that the hostname is `localhost`. + +**DOTMATRIX_USER_LOCAL** *string = "♟"* + +The marker used to indicate that the user is the same than the login one. + + +**DOTMATRIX_MARK_STASH** *string = "✝"* + +The marker used to indicate that the VCS stash is not empty. + + +**DOTMATRIX_MARK_UNTRACKED** *string = "?"* + +The marker used to indicate that there are some files that are untracked +by the VCS in the current repository. + + +**DOTMATRIX_DIFF** *string = "≠"* + +The marker used to indicate that there is some change in the VCS state +(either changes needed to be committed, or commits needed to be pushed). + + +**DOTMATRIX_VCS** *string = "╟┘"* + +The marker used to indicate that there is a VCS involved in the current directory. + + +**DOTMATRIX_MARK** *string = "■"* + +The actual prompt marker, right where the user type text. + + +**DOTMATRIX_ENABLE_GRADIENT_LINE** *boolean = 0* + +If set to 0 (the default), will draw the line of the middle section +as a sequence of `DOTMATRIX_LINE` characters, +using the `DOTMATRIX_COLOR_LINE` color. + +If set to 1, will draw the same line with a gradient of color +interpolated from `DOTMATRIX_COLOR_LINE_START` +to `DOTMATRIX_COLOR_LINE_END`. + + +#### Variant Markers + +These options are the one used to actually define the theme variants. +You may overcome them with your own configuration. + +**DOTMATRIX_LINE** *string = "━"* + +The character used to draw the middle line. + + +**DOTMATRIX_PLUG** *string = "▛"* + +The character for joined segments limits. + + +**DOTMATRIX_SOFT** *string = "╱"* + +The character for "soft" separation (e.g. path elements, branch details, jobs, etc.) + + +**DOTMATRIX_MEAN** *string = "▞"* + +The character for "mean" separation +(used when two segments of the same color are joint). + + +**DOTMATRIX_LINK** *array = ("▙" " " "▜")* + +Characters used for showing a small gap. + + +**DOTMATRIX_OPEN** *array = ("▙" " ▚ " "▜")* + +Characters used for showing a large gap. + + +**DOTMATRIX_DANG** *array = ("▙" " □ " "▜")* + +Characters used for showing a very lareg gap (i.e. a dangerous state). + + +**DOTMATRIX_ENDS** *array = ("▛▞▗ ▝" "▖ ▘▞▟")* + +Characters marking the ends of the right and left parts of the first line. + + +**DOTMATRIX_ITEMS** *array = ("┫" "┃" "┣")* + +Characters used to separate keywords in the middle line. +The middle character separates keywords of the same type (e.g. every Software Collection). + + +#### Spacing + +You may overcome the spacing details with these options. + +**DOTMATRIX_SPACE_VOID** *string = " "* + +Spacing character around segments joints marker. + + +**DOTMATRIX_SPACE_PATH** *string = " "* + +Spacing character specifically for the "current path" section. + + +**DOTMATRIX_SPACE_FIELD** *string = ""* + +Spacing character around the content of the segments themselves. + + +**DOTMATRIX_SPACE_LINE** *string = " "* + +Spacing character around the keywords of the middle line. + + +**DOTMATRIX_SPACE_FILL** *string = "█"* + +Spacing character for filled sections. +You probably don't want to touch this. + + +#### Colors + + +**DOTMATRIX_COLOR_DARK** *array = (252 239 0 0 15 0)* + +The color of dark segments. + + +**DOTMATRIX_COLOR_LITE** *array = (239 252 0 0 0 15)* + +The color of light segments. + + +**DOTMATRIX_COLOR_GLOW** *array = ( 0 252 1 0 0 15)* + +The color for bright elements. + + +**DOTMATRIX_COLOR_NOTE** *array = ( 15 33 0 0 15 12)* + +The color for notable elements. + + +**DOTMATRIX_COLOR_WARN** *array = (196 220 1 0 0 11)* + +The color for elements related to a warning. + + +**DOTMATRIX_COLOR_FAIR** *array = ( 0 244 0 0 0 8)* + +The color for elements that are not very important. + + +**DOTMATRIX_COLOR_PATH_SHORT** *array = (252 239 0 0 0 15)* + +The color of the shorten path marker. + + +**DOTMATRIX_COLOR_PATH_VCS** *array = (252 239 0 1 0 15)* + +The color of the VCS repository in the path. + + +**DOTMATRIX_COLOR_PATH_LAST** *array = (15 239 1 0 0 15)* + +The color of the current directory. + + +**DOTMATRIX_COLOR_LINE** *array = (244 -1 0 0 15 -1)* + +The color of the middle line. + + +**DOTMATRIX_COLOR_MARK** *array = (15 -1 0 0 15 -1)* + +The color of the actual prompt mark. + + +**DOTMATRIX_COLOR_SEP_DARK** *array = ( 0 -2 0 0 0 -2)* + +The color for dark separators. + + +**DOTMATRIX_COLOR_SEP_FAIR** *array = (244 -2 0 0 0 -2)* + +The color for fair separators. + + +**DOTMATRIX_COLOR_SEP_LITE** *array = ( 15 -2 0 0 15 -2)* + +The color for light separators. + + +**DOTMATRIX_COLOR_LINE_START** *array = (255 -1 1 0 15 -1)* + +The color starting the gradient of the line of the middle section. +Default is white. + +Valus being linearly interpolated up to `DOTMATRIX_COLOR_LINE_END`, +it is recommended to stick to aligned ANSI values (i.e. greys) + + +**DOTMATRIX_COLOR_LINE_END** *array = (232 -1 1 0 15 -1)* + +The color ending the gradient of the line of the middle section. +Default is black. + +Valus being linearly interpolated from `DOTMATRIX_COLOR_LINE_START`, +it is recommended to stick to aligned ANSI values (i.e. greys). + + diff --git a/dotmatrix-intro-chevron.png b/dotmatrix-intro-chevron.png new file mode 100644 index 0000000..ea01de1 Binary files /dev/null and b/dotmatrix-intro-chevron.png differ diff --git a/dotmatrix-med-chevron.png b/dotmatrix-med-chevron.png new file mode 100644 index 0000000..1c63113 Binary files /dev/null and b/dotmatrix-med-chevron.png differ diff --git a/dotmatrix-med-slant.png b/dotmatrix-med-slant.png new file mode 100644 index 0000000..b309e1d Binary files /dev/null and b/dotmatrix-med-slant.png differ diff --git a/dotmatrix-med-text.png b/dotmatrix-med-text.png new file mode 100644 index 0000000..921c1f3 Binary files /dev/null and b/dotmatrix-med-text.png differ diff --git a/dotmatrix-short-chevron.png b/dotmatrix-short-chevron.png new file mode 100644 index 0000000..ba64f68 Binary files /dev/null and b/dotmatrix-short-chevron.png differ diff --git a/dotmatrix-short-dots.png b/dotmatrix-short-dots.png new file mode 100644 index 0000000..c0114ae Binary files /dev/null and b/dotmatrix-short-dots.png differ diff --git a/dotmatrix-short-round.png b/dotmatrix-short-round.png new file mode 100644 index 0000000..3eb328a Binary files /dev/null and b/dotmatrix-short-round.png differ diff --git a/dotmatrix-short-slant.png b/dotmatrix-short-slant.png new file mode 100644 index 0000000..a49fb44 Binary files /dev/null and b/dotmatrix-short-slant.png differ diff --git a/dotmatrix-short-text.png b/dotmatrix-short-text.png new file mode 100644 index 0000000..cfec607 Binary files /dev/null and b/dotmatrix-short-text.png differ diff --git a/dotmatrix-spaced.png b/dotmatrix-spaced.png new file mode 100644 index 0000000..e9983a9 Binary files /dev/null and b/dotmatrix-spaced.png differ diff --git a/dotmatrix-unspaced.png b/dotmatrix-unspaced.png new file mode 100644 index 0000000..8b0b6b4 Binary files /dev/null and b/dotmatrix-unspaced.png differ diff --git a/liquidprompt_dotmatrix_design.svg b/liquidprompt_dotmatrix_design.svg new file mode 100644 index 0000000..b3f9e5e --- /dev/null +++ b/liquidprompt_dotmatrix_design.svg @@ -0,0 +1,3028 @@ + + + + + Liquid Prompt DotMatrix Design + + + + + + + + + + + localhost + + + logged│ home + + + ┌┴┐┌┴┐┌┴┐ + + + + X + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ~ + + + + +   + + + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + + + + + + + + + + + + + ├┘ + + + no-internet + + + admin remote dirstack detached suspended + + + X su │ tmux │ RO VCS root cwd │ batt load temp │ bg │ time + + + ├┐┌┴┐┌─┴─┐┌┴┐┌──┴──┐┌┴┐ ┌─────┴─────┐ ┌───┴────┐ ┌┴┐ ┌┴─┐┌─┴─┐┌─┴┐ ┌┴┐┌┴┐┌┴┐┌───┴───┐ + + + + + X + + + █ + + + + + + + + + + + root + + + + + + + + + + + + + + + + + + server + + + + + + + + + + + + + + + + ~ + + + + + + + + code + + + + + + + + liquidprompt + + + + + + + + + + + theme + + + + + + + + dotmatrix + + + + + + + + + + + + + + + + + +   + + + + 24% + + + + + + + + 1.68 + + + + + + + + 90° + + + +  3d + + + + + + + + 2& + + + + + + + + 1z + + + + + + + + 15:20:34 + + + ━ scl ━ venv + + + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + + + + + + + + + + + ± + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + main + + + + : + + + + feat + + + + + + + + v0.1 + + + + + + + + + + + + + + + + + + + + + + + + + + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + detached + + + + + + + + + + 20s + + + + + + + + + + + + + + 125 + + + + + + + + + + ├┘└┬┘├┘└──┬──┘└─┬──┘└─┬┘└─┬─┘ ├┘└───┬───┘└┬┘└┬┘└───┬───┘└┬─┘ └┬─┘ ├┘ + + + │VCS push!│ │bookmark │ commit! │ stash │ head st. Runtime│ sudo + + + itnet upstream branch tag diff untracked error + + + ssh + + + txt│ guest FQDN chroot shorten + + + ├┐┌┴┐┌──┴───┐ ┌────┴─────┐┌┴┐ ┌┴┐ + + + + + T + + +  + + + + + + + + + + + rycieos + + + + + + + + + + host.fq.dn + + +  + + + + + + + + + + + + + ~ + + + + + + + + code + + + + + + + + + + + + + + + + files + + +   + + + + + + + ━ pyenv ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + + + + + + + + + + + + + + + 1 + + + + + + + + + telnet chroot + RO + + + ┌─┴─┐ ┌─┴──┐ + + + + + T + + + + + +  + + + + + + + + + + + nojhan + + + + + + + + + + host + + + + + +  + + + + + + + + + + + + + ~ + + + + + + + + code + + + + + + + + + + + + + + + + here + + +   + + + + + + 15:20:34 + + + ━ devtoolset-8 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + + + + + +  + + + + ± + + + + + + + + + + main + + + + +   + + + └┬┘ + + + proxy + + + Generic example: + + + + X + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ~ + + + + + + + + + + code + + + + + + + + liquidprompt + + + + + + + + + + + theme + + + + + + + + dotmatrix + + +   + + + + + + 15:20:34 + + + ━━━━━━━━━━━━━━ + + + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + + + + + + + + + + + ± + + + + + + + + + + + + + + + + + + + + + + + + dotmatrix + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Liquid Prompt DotMatrix Design + 2021-02-07 + + + nojhan + + + + + +