updated and fixed doc (markdown spellcheck)

README.md

@@ -1,25 +1,30 @@
 # profile
+
 This project aims to create an advanced bash profile. It includes aliases,
 a customized prompt and several functions for different purposes. It's mostly
 targeted to system administrators but might satisfy some regular users.
 
 ## 1. Requirements
+
 profile requires **Bash 4.3 or higher** (for associative arrays and namerefs).
 It will refuse to load on older versions and will also refuse to load if the
 current shell is not bash.
 
 ## 2. Getting started
+
 Download and extract (or use git clone) the profile archive into your home
 directory.
 
 The profile is designed to be **sourced**, not executed directly.
 
 Manual setup:
+
 ```bash
 source <installpath>/profile/profile.sh
 ```
 
 Automatic setup (recommended):
+
 ```bash
 bash <installpath>/profile/profile.sh --install
 ```
@@ -34,6 +39,7 @@ bash <installpath>/profile/profile.sh --install --profile
 
 You may also set the `PROFILE_PATH` environment variable before sourcing if you
 want to override the automatic path detection:
+
 ```bash
 export PROFILE_PATH=/opt/profile
 source /opt/profile/profile.sh
@@ -48,6 +54,7 @@ files might interfere with some aliases and functions defined in profile.
 
 In interactive shells (typical terminal sessions), profile enables
 interactive-only features such as:
+
 - aliases from `[aliases]`
 - bash completion scripts from `profile.d/bash-completion/`
 - prompt initialization (`PROMPT_COMMAND` and timer hook)
@@ -58,27 +65,32 @@ intentionally skipped to avoid side effects and startup noise. Public functions
 remain available after sourcing, so scripts can still call profile helpers.
 
 ### 2.2. Initial configuration
+
 Copy the example configuration file and customise it to your needs:
+
 ```bash
 cp <installpath>/profile/doc/profile.conf.example <installpath>/profile/profile.conf
 ```
+
 `profile.conf` is git-ignored so your personal settings will never be
 accidentally committed. All keys are optional — sensible defaults apply when
 unset. See [section 4](#4-configuration) for the full reference.
 
 ## 3. What's the purpose?
+
 profile gives access to numerous functions, aliases and to an advanced prompt.
 All functions are organized into modules under the `profile.d/` directory and
 are loaded automatically at startup.
 
 ### 3.1. Prompt
+
 A bar-style prompt showing current time, execution time of the last command
 (with sub-millisecond precision), and the exit code of the last command.
 
 ### 3.2. Functions reference
 
 | Function | Module | Description |
-|---|---|---|
+| --- | --- | --- |
 | `busy` | fun | Monitor /dev/urandom for a hex pattern — look busy |
 | `check_updates` | updates | Check whether a newer profile version is available online; when called with `-q` at startup a 3-second network timeout is applied so a slow or absent network never delays the prompt |
 | `clean` | filefct | Erase backup files in given directories, optionally recursive |
@@ -129,6 +141,7 @@ A bar-style prompt showing current time, execution time of the last command
 | `showinfo` | info | Display welcome banner and system information (figlet + neofetch/fastfetch) |
 | `ssr` | ssh | SSH into a server as root, forwarding extra ssh options |
 | `taz` | compress | Compress files and directories into a chosen archive format |
+| `term_set` | conf | Set `TERM` to the best available terminal capability |
 | `urlencode` | net | URL-encode a string |
 | `utaz` | compress | Smartly uncompress archives (zip, tar.gz/bz2/xz/lz, rar, arj, lha, ace, 7z, zst, cpio, cab, deb, rpm) |
 | `ver` | info | Display the installed profile version |
@@ -144,6 +157,7 @@ any custom completion definitions. profile already ships completions for its git
 helper functions there (`git-completion.sh`).
 
 ## 4. Configuration
+
 profile uses an INI-style configuration file (`profile.conf`) located in the
 same directory as `profile.sh`. Sections are declared with `[section_name]` and
 keys follow `key = value` syntax. Each module calls `load_conf "<section>"` at
@@ -158,11 +172,32 @@ template at `doc/profile.conf.example` (see [section 2.2](#22-initial-configurat
 ### 4.1. Core sections
 
 | Section | Purpose |
-|---|---|
-| `[system]` | Bash history size, pager, and other shell behaviours |
+| --- | --- |
+| `[system]` | Bash history size, pager, terminal type, and other shell behaviours |
 | `[general]` | General-purpose variables (e.g. compilation flags, `MAKEFLAGS`) |
 | `[aliases]` | User command aliases, loaded for interactive shells only |
 
+#### `TERM` — terminal type detection
+
+The `TERM` key in `[system]` has special handling via `term_set`, which runs
+automatically at startup:
+
+| Value | Behaviour |
+| --- | --- |
+| *(absent or `smart`)* | Auto-detect the best available `terminfo` entry (default) |
+| any other string | Exported as-is — standard Unix behaviour |
+
+When auto-detection runs, emulator hints are checked in order, and the best
+`terminfo` entry confirmed to exist on the system is selected:
+
+1. **`$COLORTERM`** — `truecolor` or `24bit` → `xterm-direct`, then `xterm-256color`
+2. **`$TERM_PROGRAM`** — `iTerm.app`, `WezTerm`, `Hyper`, `vscode` → appropriate entry
+3. **`$VTE_VERSION`** — GNOME Terminal, Tilix, … → `vte-256color`, then `xterm-256color`
+4. **`$WT_SESSION`** — Windows Terminal → `xterm-256color`
+5. **`$TMUX`** — tmux session → `tmux-256color`, then `screen-256color`
+6. **`$STY`** — GNU screen session → `screen-256color`, then `screen`
+7. **Generic probe** — `xterm-256color` → `xterm-color` → `xterm` → `vt100`
+
 ### 4.2. Module defaults
 
 Each module exposes its hardcoded defaults as configuration keys. Set a key to
@@ -171,7 +206,7 @@ change the default without having to pass flags every time.
 **`[compress]`** — `taz` / `utaz`
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `TAZ_DEFAULT_FORMAT` | `tar.gz` | Archive format for `taz` (`tar.gz`, `tar.bz2`, `tar.xz`, `zip`, …) |
 | `TAZ_DEFAULT_THREADS` | `auto` | Compression threads (`auto` = runtime CPU count, or explicit positive integer) |
 | `TAZ_DEFAULT_LEVEL` | `6` | Compression level (1–9) |
@@ -181,7 +216,7 @@ change the default without having to pass flags every time.
 **`[filefct]`** — file utilities
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `EXPANDLIST_DEFAULT_SEPARATOR` | ` ` (space) | Separator used by `expandlist` |
 | `CLEAN_DEFAULT_RECURSIVE` | `0` | Set to `1` to make `clean` recurse into subdirectories |
 | `RMSPC_DEFAULT_CHAR` | `_` | Replacement character used by `rmspc` |
@@ -190,7 +225,7 @@ change the default without having to pass flags every time.
 **`[rain]`** — screensavers
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `RAIN_DEFAULT_SPEED` | `0.1` | Falling speed for `rain` |
 | `RAIN_DEFAULT_COLOR` | `Green` | Colour for `rain` |
 | `RAIN_DEFAULT_DENSITY` | dynamic | Maximum number of simultaneous falling elements for `rain` |
@@ -203,13 +238,13 @@ change the default without having to pass flags every time.
 **`[ssh]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `SSH_DEFAULT_OPT` | _(empty)_ | Extra options passed to `ssr` (e.g. `-Y` for X forwarding) |
 
 **`[pwd]`** — password tools
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `GENPWD_DEFAULT_LENGTH` | `16` | Generated password length |
 | `GENPWD_DEFAULT_OCCURS` | `1` | Number of character class occurrences |
 | `GENPWD_DEFAULT_COUNT` | `1` | Number of passwords to generate |
@@ -222,7 +257,7 @@ change the default without having to pass flags every time.
 **`[fun]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `BUSY_DEFAULT_PATTERN` | `[0-9a-f]` | Hex pattern matched by `busy` |
 | `BUSY_DEFAULT_DELAY` | `0.1` | Polling delay (seconds) for `busy` |
 | `FAKE_COMPILE_DEFAULT_MIN_DELAY` | `40` | Min delay between output lines for `fake_compile` (ms) |
@@ -234,7 +269,7 @@ change the default without having to pass flags every time.
 **`[git]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `GIT_MAIN_BRANCH` | `main` | Fallback main branch name used when remote HEAD cannot be detected |
 | `GIT_DEFAULT_REMOTE` | `origin` | Default remote used by git helper functions |
 | `GIT_WIP_PREFIX` | `wip` | Prefix used by `gwip` when generating automatic checkpoint messages |
@@ -243,13 +278,13 @@ change the default without having to pass flags every time.
 **`[info]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `METEO_DEFAULT_CITY` | _(empty)_ | Default city for `meteo` when no argument is given |
 
 **`[net]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `DWL_PREFERRED_TOOL` | _(empty)_ | Force `dwl` to use `curl`, `wget`, or `fetch` (auto-detected when unset) |
 | `DWL_DEFAULT_RESUME` | `0` | Enable `dwl` resume mode by default (`1`/`true`/`yes`/`on`); applies to file downloads |
 | `MYEXTIP_DEFAULT_URL` | `https://ip-api.com/json` | API endpoint used by `myextip` |
@@ -257,20 +292,20 @@ change the default without having to pass flags every time.
 **`[packages]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `PKGS_DEFAULT_IGNORE_CASE` | `0` | Set to `1` to make `pkgs` case-insensitive by default |
 
 **`[processes]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `PPU_DEFAULT_FORMAT` | `pid,user,comm,args` | `ps` output format used by `ppu` |
 | `KU_DEFAULT_SIGNAL` | `TERM` | Default signal sent by `ku` |
 
 **`[updates]`**
 
 | Key | Default | Description |
-|---|---|---|
+| --- | --- | --- |
 | `UPDT_DEFAULT_BRANCH` | `master` | Git branch used for update checks and `profile_upgrade`. Changing this value causes `profile_upgrade` to automatically switch the local checkout to the new branch on the next run and display a warning. |
 
 ### 4.3. Locale shortcuts
@@ -342,7 +377,7 @@ PROMPT_COLOR_DIR_FG  = $IYellow
 The twelve available `PROMPT_COLOR_*` keys are:
 
 | Key | Role |
-|---|---|
+| --- | --- |
 | `PROMPT_COLOR_TIME_FG` / `TIME_BG` | Clock foreground / background |
 | `PROMPT_COLOR_BAR_BG` | Main bar background |
 | `PROMPT_COLOR_OK_FG` / `OK_MARK` | Exit-code text / checkmark on success |
@@ -397,19 +432,23 @@ and other colour-aware tools.
 True-colour themes (`solarized`, `solarized-light`) require a terminal with
 24-bit colour support (Konsole, iTerm2, kitty, Alacritty, Windows Terminal).
 Verify support with:
+
 ```bash
 printf '\e[38;2;38;139;210mTrue colour test\e[0m\n'
 ```
 
 ## 5. Contact and more information
+
 ### 5.1. New users
+
 If you use (or plan to use) `profile`, I'll be happy if you simply mail me to
 let me know, especially if you don't plan to contribute. If you plan to
 contribute, I'll be twice happier for sure!
 
 ### 5.2. Bugs
+
 **profile** bug tracker is hosted on its Gitea instance. Check the
-https://git.geoffray-levasseur.org/fatalerrors/profile page. If you find a bug,
+<https://git.geoffray-levasseur.org/fatalerrors/profile> page. If you find a bug,
 you can also submit a bug report to the maintainer mail address mentioned at
 the end of that document. A bug report may contain the command line parameters
 where the bug happens, OS details, the module that triggered it, if any, and the
@@ -422,6 +461,7 @@ Check the [FAQ](./doc/FAQ.md) and the [to-do list](./doc/todo.md) before
 sending any feature request or bug report, as it might already be documented.
 
 ### 5.3. How to contribute?
+
 You are free to improve and contribute as you wish. If you have no idea what to
 do or want some direction, you can check the [to-do list](./doc/todo.md),
 containing desired future improvements. Make sure you always have the latest
@@ -443,6 +483,7 @@ installation will probably be rejected.
 If you want to make a financial contribution, please contact me by mail.
 
 ### 5.4. License, website, and maintainer
+
 Everything except configuration files is licensed under the BSD-3 license.
 Please check the license file alongside this one.
 
@@ -455,4 +496,4 @@ You can mail the author at fatalerrors \<at\> geoffray-levasseur \<dot\> org.
 Documentation (c) 2021-2026 Geoffray Levasseur.
 
 This file is distributed under the 3-clause BSD license. The complete license
-agreement can be obtained at: https://opensource.org/licenses/BSD-3-Clause
+agreement can be obtained at: <https://opensource.org/licenses/BSD-3-Clause>