ble.sh & z4h addition

1 files changed, 119 insertions, 0 deletions

diff --git a/.local/src/blesh/doc/CONTRIBUTING.md b/.local/src/blesh/doc/CONTRIBUTING.md
new file mode 100644
index 0000000..03d44ae
--- /dev/null
+++ b/.local/src/blesh/doc/CONTRIBUTING.md
@@ -0,0 +1,119 @@
+# Contribution Guide
+
+## How to contribute
+
+### Issues
+
+You can freely create an issue using the following links:
+
+- Report and fixes for bugs and performance issues [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=bug_report.md)
+- Questions on usage [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=feature_request.md)
+- Feature request [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=help.md)
+- Others (suggestions, projects, discussion, complaints, news, information or anything) [[Here]](https://github.com/akinomyoga/ble.sh/issues/new?template=free_style.md)
+
+### Pull requests
+
+We always welcome following types of pull requests. Any changes will be considered to be provided under the BSD 3-Clause License.
+If you do not know whether your changes would be appropriate for merge, please feel free to create a pull request and let us talk with each other!
+
+- Better translation to English, typo fixes
+- Fixes, optimization, test cases
+- New features
+- New color themes ... We accept new themes in [`contrib`](https://github.com/akinomyoga/blesh-contrib/pulls) repository.
+- Others
+
+### Wiki
+
+You can freely edit [wiki pages](https://github.com/akinomyoga/ble.sh/wiki).
+
+- Translations
+- Typo fixes
+- Create new pages
+
+## For package maintainers
+
+If you are a package maintainer for a repository of Linux distribution, etc.
+you may provide a package-specific setting by preparing
+a file `/path/to/blesh/lib/_package.sh` (e.g. `/usr/share/blesh/lib/_package.sh`)
+which will be sourced after the load of `ble.sh` just before sourcing user's configuration (`~/.blerc`).
+
+- In the file, the shell variable `_ble_base_package_type=TYPE` should be
+   set up to have a repository-specific name (such as `AUR`). 
+
+- The function named `ble/base/package:TYPE/update` (where `TYPE`
+  matches with a value assigned to `_ble_base_package_type`) may be
+  provided to define a custom updating procedure.  The exit status of the function can be
+  - `0` ... when the update successed
+  - `6` ... when the update was skipped because the package was up to date.
+  - `125` ... when it wants to fallback to the built-in updating procedure of `ble.sh`.
+  - Other ... when the update failed
+
+An example `lib/_package.sh` might be
+
+```bash
+_ble_base_package_type=apt
+
+function ble/base/package:apt/update {
+  sudo apt upgrade blesh
+}
+```
+
+You can also find a real example for AUR (Arch User Repository) [here](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git).
+
+## Summary of codebase
+
+The core script file `ble.sh` is generated by combining the following files:
+
+- `ble.pp` ... Basic initialiation
+- `src/def.sh` ... Prototype definitions
+- `src/util.sh` ... Basic utility functions
+- `src/decode.sh` ... User-input decoder and keybindings
+- `src/color.sh` ... Terminal graphic attributes
+- `src/canvas.sh` ... Terminal layout engine
+  - `src/canvas.emoji.sh` ... Emoji database
+- `src/history.sh` ... Command history management
+- `src/edit.sh` ... Line editor
+- `src/benchmark.sh` ... Measure processing time
+- `lib/core-completion.sh` ... Prototype definition for completions
+- `lib/core-syntax.sh` ... Prototype definitions for syntax analyzer
+
+Useful features are implemented in separate modules:
+
+- `keymap/vi.sh` ... Vim mode
+  - `lib/vim-arpeggio.sh` ... `vim-arpeggio`-like plugin
+  - `lib/vim-surround.sh` ... `vim-surround`-like plugin
+- `keymap/emacs.sh` ... Emacs mode
+- `lib/core-syntax.sh` ... Shell parser and syntax highlighting
+  - `lib/core-syntax-ctx.def` ... Definition of parser states
+- `lib/core-complete.sh` ... Completions including `menu-complete`, `auto-complete`, `menu-filter`, `dabbrev`, `sabbrev`, etc.
+
+The following files are initialization scripts:
+
+- `lib/init-term.sh` ... Initialize terminal escape sequences (host-to-terminal, i.e. control sequences)
+- `lib/init-cmap.sh` ... Initialize terminal escape sequences (terminal-to-host, i.e. key sequences)
+- `lib/init-bind.sh` ... Initialize readline attacher
+- `lib/init-msys1.sh` ... Workaround for MSYS1 with broken pipes
+  - `lib/init-msys1-helper.c` ... Helper C program for the workaround of broken pipes
+
+## Tests
+
+Tests can be run by one of the following commands:
+
+```bash
+$ make check
+$ make check-all
+$ bash out/ble.sh --test
+
+```
+
+Currently test coverage is very small
+partly because the testing for interactive behavior and terminal rendering results is hard.
+Nevertheless, the tests are defined in the following files:
+
+- `lib/core-test.sh` ... Library for tests
+- `lib/test-main.sh`
+- `lib/test-util.sh`
+- `lib/test-canvas.sh`
+- `lib/test-edit.sh`
+- `lib/test-complete.sh`
+- `lib/test-syntax.sh`