From c14acaf6d011b273520ef8c7f18efba1d3c9652e Mon Sep 17 00:00:00 2001 From: pvincent Date: Mon, 10 Aug 2026 17:37:32 +0400 Subject: [PATCH] documentation rewritten --- README.md | 88 +++++++++++++++------------------------------- doc/bash_tips.md | 38 ++++++++++++++++++++ doc/development.md | 8 +++++ doc/index.md | 5 ++- doc/todo.md | 5 +++ 5 files changed, 83 insertions(+), 61 deletions(-) create mode 100644 doc/bash_tips.md create mode 100644 doc/development.md create mode 100644 doc/todo.md diff --git a/README.md b/README.md index 71d5396..1015854 100644 --- a/README.md +++ b/README.md @@ -2,86 +2,54 @@ MIAOU-BASH is a mix of scripts and settings aiming for leveraging your terminal experience. As the name suggests, it is based on Bash -and expect to work on any modern GNU/Linux. +and expect to work on most of any modern GNU/Linux. However, at +this stage, the installation process only supports 2 distribution families: -Actually the installation process supports only 2 distros: Debian and Arch Linux. -This package works either standalone or as a core dependency of any other -miaou-* utilities. +* Debian *Like* : Debian, Mint, Ubuntu, ... +* Arch *Like* : ArchLinux, Manjaro, ... -Be aware (uppercase) MIAOU-BASH refer to a bunch of scripts and configuration settings. -Meanwhile (downcase) `miaou-bash` refer to only one of these scripts, -maybe the most useful one! +Be aware MIAOU-BASH (uppercase) refers to the whole package itself. +Meanwhile `miaou-bash` (downcase) refers to the only one, yet useful, utility script. This is free software and licensed as: Affero GPL v3 + -Any feedback would be appreciated. -[contact@artcode.re](mailto:contact@artcode.re) +Any feedback appreciated: [contact@artcode.re](mailto:contact@artcode.re) ## Featuring -* [x] miaou-bash * [x] default settings * [x] inputrc - * [x] vimrc * [x] bashrc -* [x] semver-git_tag -* [x] some aliases (l, ll, ltr, ...) -* [x] smart prompt - * [x] git, failure aware + * [x] some aliases (l, ll, ltr, ...) + * [x] smart prompt + * [x] git, failure aware + * [x] vimrc +* [x] miaou-bash + * [x] error-prone + * [x] stacktrace +* [x] tools + * [x] semver-git_tag + * [x] fqdn ## install -```bash -curl -s https://git.artcode.re/miaou/miaou-bash/raw/branch/main/install.sh | sudo bash && exec bash -``` +`curl -s https://git.artcode.re/miaou/miaou-bash/raw/branch/main/install.sh | sudo bash && exec bash` ## upgrade -```bash -miaou-bash --self-upgrade -``` +`miaou-bash --self-upgrade` ## uninstall -```bash -miaou-bash --uninstall - -``` - -## development mode (credentials required) - -* REAL_DIR=/opt/miaou-bash -* sudo mkdir -m 755 $REAL_DIR && sudo chown $(id -un) $REAL_DIR -* git clone :miaou/miaou-bash.git $REAL_DIR -* DEV_DIR=$HOME/DEV/BASH/miaou-bash # change DEST according to your needs! -* ln -s $REAL_DIR $DEV_DIR -* cd $REAL_DIR && sudo ./install.sh - -## useful library - -* source /opt/miaou-bash/lib/functions.bash +`miaou-bash --uninstall && exec bash` -## extra bindkeys - -* CTRL LEFT, RIGHT => move around words, back and forward -* CTRL DELETE, BACKSPACE => delete word -* ALT DELETE, BACKSPACE => delete line from cursor -* CTRL + SHIFT + / => undo +## Readline main bindings ```bash -# moving around words with CTRL+Left or CTRL+Right -# moving around Big Words with ALT+Left or ALT+Right (faster) -# suppressing word with CTRL+Backspace or CTRL+Delete -# suppressing until start/end with ALT+Backspace or ALT+Delete (faster) -# suppressing whole line with SHIFT+Delete or SHIFT+Backspacemoving around words with CTRL + Left or CTRL + Right -# undo with CTRL+SHIFT+/ +# CTRL + { left, right } for moving around words +# ALT + { left, right } for moving around Big:Words (faster) +# CTRL + { backspace, delete } for word suppressing +# ALT + { backspace, delete } for suppressing until start/end (faster) +# SHIFT + { backspace, delete } for suppressing the whole line +# { CTRL, ALT } + u for undo +# { up, down } for history search ``` - -## TODO - -* [ ] prompt git shows version with `+` when there is more than one commit over current version. ie: v0.0.0 + 2 commits more should display v-1.0.0+ -* [ ] semver_git_tag should append `RELEASE_NOTES.md` from this TODO markdown file, providing that NEW NOTE section below contains appropriate items to fulfill the current release note - * [ ] git log ..HEAD --oneline - -NEW NOTE -======== - diff --git a/doc/bash_tips.md b/doc/bash_tips.md new file mode 100644 index 0000000..9aae9ea --- /dev/null +++ b/doc/bash_tips.md @@ -0,0 +1,38 @@ +# Bash Tips + +## prevent last false + +function body should not end up with a ternary statement + +### wrong last + +Compound of 2 'false' statement returns false. + +```bash +[[ : ]] && [[ : ]] +``` + +### right last + +```bash +[[ : ]] && [[ : ]] || true +``` + +## arithmetic issue + +last (++) statement does not complete successfully! + +### wrong ++ + +```bash +count=0 +(( ++count )) # ok +(( ++count )) # last statement in function returns false +``` + +### right ++ + +```bash +count=0 +count=$((count+1)) +` diff --git a/doc/development.md b/doc/development.md new file mode 100644 index 0000000..576c6f9 --- /dev/null +++ b/doc/development.md @@ -0,0 +1,8 @@ +# development mode (credentials required) + +* REAL_DIR=/opt/miaou-bash +* sudo mkdir -m 755 $REAL_DIR && sudo chown $(id -un) $REAL_DIR +* git clone :miaou/miaou-bash.git $REAL_DIR +* DEV_DIR=$HOME/DEV/BASH/miaou-bash # change DEST according to your needs! +* ln -s $REAL_DIR $DEV_DIR +* cd $REAL_DIR && sudo ./install.sh diff --git a/doc/index.md b/doc/index.md index 2b53121..b7cc8cc 100644 --- a/doc/index.md +++ b/doc/index.md @@ -1,5 +1,9 @@ # Documentation +* [Bash Tips](./bash_tips.md) +* [Development Mode](./development.md) +* [TODO](./todo.md) + ## prevent last false function body should not end up with a ternary statement @@ -36,4 +40,3 @@ count=0 count=0 count=$((count+1)) ``` - diff --git a/doc/todo.md b/doc/todo.md new file mode 100644 index 0000000..1220625 --- /dev/null +++ b/doc/todo.md @@ -0,0 +1,5 @@ +# TODO + +* [ ] prompt git shows version with `+` when there is more than one commit over current version. ie: v0.0.0 + 2 commits more should display v-1.0.0+ +* [ ] semver_git_tag should append `RELEASE_NOTES.md` from this TODO markdown file, providing that NEW NOTE section below contains appropriate items to fulfill the current release note + * [ ] git log ..HEAD --oneline