documentation rewritten

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] 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 <git@artcode.re>: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 <LATEST_TAG>..HEAD --oneline
-
-NEW NOTE
-========
-

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))
+`

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 <git@artcode.re>: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

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))
 ```
-

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 <LATEST_TAG>..HEAD --oneline